System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 717d961e2508b178f0db6197f65e39ccb67729d7:


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 38 2e 37 2e 31 22 0a 23 64 65 66 69 6e 65 20  .8.7.1".#define 
1030: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1040: 55 4d 42 45 52 20 33 30 30 38 30 30 37 0a 23 64  UMBER 3008007.#d
1050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
1060: 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31  RCE_ID      "201
1070: 34 2d 31 30 2d 32 39 20 31 33 3a 35 39 3a 35 36  4-10-29 13:59:56
1080: 20 33 62 37 62 37 32 63 34 36 38 35 61 61 35 63   3b7b72c4685aa5c
1090: 66 35 65 36 37 35 63 32 63 34 37 65 62 65 63 31  f5e675c2c47ebec1
10a0: 30 64 39 37 30 34 32 32 31 22 0a 0a 2f 2a 0a 2a  0d9704221"../*.*
10b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
10c0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
10d0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20  sion Numbers.** 
10e0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
10f0: 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74  3_version, sqlit
1100: 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a  e3_sourceid.**.*
1110: 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63  * These interfac
1120: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73  es provide the s
1130: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1140: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56  as the [SQLITE_V
1150: 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c  ERSION],.** [SQL
1160: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1170: 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  ER], and [SQLITE
1180: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
1190: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
11a0: 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73  s.** but are ass
11b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
11c0: 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64   library instead
11d0: 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66   of the header f
11e0: 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73  ile.  ^(Cautious
11f0: 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  .** programmers 
1200: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73  might include as
1210: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
1220: 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69  s in their appli
1230: 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72  cation to.** ver
1240: 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20  ify that values 
1250: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1260: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74  e interfaces mat
1270: 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e  ch the macros in
1280: 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20  .** the header, 
1290: 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20  and thus insure 
12a0: 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  that the applica
12b0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  tion is.** compi
12c0: 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e  led with matchin
12d0: 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65  g library and he
12e0: 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  ader files..**.*
12f0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1300: 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73  re>.** assert( s
1310: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1320: 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49  n_number()==SQLI
1330: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1340: 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  R );.** assert( 
1350: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73  strcmp(sqlite3_s
1360: 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45  ourceid(),SQLITE
1370: 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29  _SOURCE_ID)==0 )
1380: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1390: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
13a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
13b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
13c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
13d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
13e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
13f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1400: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1410: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1420: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1430: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1450: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1470: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1480: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1490: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
14a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
14b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
14c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
14d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
14e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
14f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1500: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1510: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1520: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1530: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1540: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1550: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1560: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1570: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1580: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1590: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
15a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
15b0: 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f  urceid() functio
15c0: 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20  n returns .** a 
15d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
15e0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f  ing constant who
15f0: 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  se value is the 
1600: 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20  same as the .** 
1610: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  [SQLITE_SOURCE_I
1620: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  D] C preprocesso
1630: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  r macro..**.** S
1640: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1650: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
1660: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
1670: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  d()]..*/.SQLITE_
1680: 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
1690: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
16a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
16b0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16c0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
16d0: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
16e0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
16f0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1700: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
1710: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1720: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1730: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1740: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1750: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1760: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1770: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1780: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1790: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
17a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
17b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
17c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
17d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
17e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
17f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1800: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1810: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1820: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1830: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1840: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1850: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1860: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1870: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1880: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1890: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
18a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
18b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
18c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
18d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
18e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
18f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1900: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1910: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1920: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1930: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1940: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1950: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1960: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1970: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1980: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1990: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
19a0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
19b0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
19c0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19d0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
19e0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
19f0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1a00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1a10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1a30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1a40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1a50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1a60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1a70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1aa0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1ab0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1ac0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1ad0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1ae0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1af0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1b00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1b10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1b20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1b30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1b40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1b50: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  GS.SQLITE_API in
1b60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  t sqlite3_compil
1b70: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e  eoption_used(con
1b80: 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d  st char *zOptNam
1b90: 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  e);.SQLITE_API c
1ba0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1bb0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1bc0: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e  _get(int N);.#en
1bd0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
1be0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1bf0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1c00: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
1c10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c20: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1c30: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1c40: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1c50: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1c60: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1c70: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1c80: 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a  tted due to the.
1c90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
1ca0: 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  DSAFE] compile-t
1cb0: 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67  ime option being
1cc0: 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a   set to 0..**.**
1cd0: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
1ce0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
1cf0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
1d00: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53    When.** the [S
1d10: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1d20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1d30: 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32   macro is 1 or 2
1d40: 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  , mutexes.** are
1d50: 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c   enabled and SQL
1d60: 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ite is threadsaf
1d70: 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20  e.  When the.** 
1d80: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d90: 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20  FE] macro is 0, 
1da0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20  .** the mutexes 
1db0: 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69  are omitted.  Wi
1dc0: 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65  thout the mutexe
1dd0: 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66  s, it is not saf
1de0: 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69  e.** to use SQLi
1df0: 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20  te concurrently 
1e00: 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f  from more than o
1e10: 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ne thread..**.**
1e20: 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   Enabling mutexe
1e30: 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75  s incurs a measu
1e40: 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63  rable performanc
1e50: 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f  e penalty..** So
1e60: 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20   if speed is of 
1e70: 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63  utmost importanc
1e80: 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73  e, it makes sens
1e90: 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e to disable.** 
1ea0: 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75  the mutexes.  Bu
1eb0: 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61  t for maximum sa
1ec0: 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68  fety, mutexes sh
1ed0: 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e  ould be enabled.
1ee0: 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1ef0: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72   behavior is for
1f00: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65   mutexes to be e
1f10: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  nabled..**.** Th
1f20: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1f30: 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61   be used by an a
1f40: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61  pplication to ma
1f50: 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65  ke sure that the
1f60: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
1f70: 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73  QLite that it is
1f80: 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74   linking against
1f90: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1fa0: 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65  th.** the desire
1fb0: 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65  d setting of the
1fc0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1fd0: 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  AFE] macro..**.*
1fe0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1ff0: 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e   only reports on
2000: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2010: 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a  e mutex setting.
2020: 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
2030: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c  E_THREADSAFE] fl
2040: 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ag.  If SQLite i
2050: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
2060: 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  ** SQLITE_THREAD
2070: 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65  SAFE=1 or =2 the
2080: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e  n mutexes are en
2090: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
20a0: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66   but.** can be f
20b0: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c  ully or partiall
20c0: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  y disabled using
20d0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
20e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a  te3_config()].**
20f0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20   with the verbs 
2100: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2110: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53  INGLETHREAD], [S
2120: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2130: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72  TITHREAD],.** or
2140: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2150: 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72  MUTEX].  ^(The r
2160: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2170: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2180: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2190: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
21a0: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
21b0: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
21c0: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
21d0: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
21e0: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
21f0: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2200: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
2210: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
2220: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
2230: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
2250: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
2260: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2270: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2280: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2290: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
22a0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
22b0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
22c0: 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ation..*/.SQLITE
22d0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
22e0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
22f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2300: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2310: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2320: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2330: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2340: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
2350: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
2360: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
2370: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2380: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2390: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
23a0: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
23b0: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
23c0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
23d0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
23e0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
23f0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2400: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2410: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2420: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2430: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2440: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2450: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
2460: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
2470: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2480: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
2490: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
24a0: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
24b0: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
24c0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
24d0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
24e0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
24f0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2500: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2510: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2520: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2530: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2540: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
2550: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
2560: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
2570: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
2580: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2590: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
25a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25b0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
25c0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
25d0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
25e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
25f0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2600: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2610: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2620: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2630: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2640: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
2650: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
2660: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
2670: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2680: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2690: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
26a0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
26b0: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
26c0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
26d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
26e0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
26f0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2700: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2710: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2720: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2730: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2740: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2750: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
2760: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
2770: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
2780: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
2790: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
27a0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
27b0: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
27c0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
27d0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
27e0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
27f0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2800: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2810: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2820: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2830: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2840: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2850: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2870: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2880: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2890: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
28a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
28b0: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
28c0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
28d0: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
28e0: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
28f0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2900: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2910: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2930: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2940: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2950: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2960: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2970: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2980: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2990: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
29a0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
29b0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
29c0: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
29d0: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
29e0: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
29f0: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2a00: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2a10: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2a20: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2a30: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2a40: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2a50: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2a60: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2a70: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2a80: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2a90: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2aa0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2ab0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2ac0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2ad0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2ae0: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2af0: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2b00: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2b10: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2b20: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2b30: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2b40: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2b50: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2b60: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2b70: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2b80: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2b90: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ba0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2bb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2bc0: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2bd0: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2be0: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2bf0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2c00: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2c10: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2c20: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2c30: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2c40: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2c50: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2c60: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2c70: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2c80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c90: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2ca0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2cb0: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2cc0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2cd0: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2ce0: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2cf0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2d00: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2d10: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2d20: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2d30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2d40: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2d50: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2d60: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2d70: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2d80: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2d90: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2da0: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2db0: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2dc0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2dd0: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2de0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2df0: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2e00: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2e10: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2e20: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2e30: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2e40: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2e50: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2e60: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2e70: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2e80: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2e90: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2ea0: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2eb0: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2ec0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2ed0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2ee0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2ef0: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2f00: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2f10: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2f20: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2f30: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2f40: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2f50: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2f60: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2f70: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2f80: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2f90: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2fa0: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2fb0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2fc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2fd0: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2fe0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2ff0: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
3000: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
3010: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
3020: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3030: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
3040: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3050: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
3060: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
3070: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
3080: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
3090: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
30a0: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
30b0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
30c0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
30d0: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
30e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30f0: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3100: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3110: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3120: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3130: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
3140: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
3150: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
3160: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
3170: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
3180: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
3190: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
31a0: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
31b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
31c0: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
31d0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
31e0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
31f0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3200: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3210: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3220: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3230: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
3240: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
3250: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
3260: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
3270: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
3280: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
3290: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
32a0: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
32b0: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
32c0: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
32d0: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53  less no-op..*/.S
32e0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
32f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
3300: 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
3310: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
3320: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3330: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3340: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3350: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
3360: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
3370: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
3380: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
3390: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
33a0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
33b0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
33c0: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
33d0: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
33e0: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
33f0: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3400: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3410: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3420: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3430: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3440: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3450: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3460: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
3470: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
3480: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
3490: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34a0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34b0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34c0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
34d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
34e0: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
34f0: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3500: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3510: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3520: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3530: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3540: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3550: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3560: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
3570: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
3580: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
3590: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35a0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35b0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35c0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
35d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35e0: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
35f0: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3600: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3610: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3620: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3630: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3640: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3650: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3660: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
3670: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
3680: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
3690: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36a0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36b0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
36d0: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
36e0: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
36f0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3700: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3710: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3720: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3730: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3740: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3750: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3760: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
3770: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
3780: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
3790: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37a0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37b0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37c0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
37d0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
37e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
37f0: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3800: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3810: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3820: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3830: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3840: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3850: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3860: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3870: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
3880: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
3890: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38a0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38b0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38c0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
38d0: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
38e0: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
38f0: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3900: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3910: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3920: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3930: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3940: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3950: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3960: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3970: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3980: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
3990: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39a0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39b0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39c0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
39d0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39f0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a00: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a10: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a20: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a30: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a40: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a50: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a60: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3a70: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3a80: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3a90: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3aa0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ab0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ac0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3ad0: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3ae0: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3af0: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b00: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b10: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b20: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b30: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b40: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b50: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b60: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3b70: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3b80: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3b90: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ba0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3bb0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bc0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3bd0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3be0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3bf0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c00: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c10: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c20: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c30: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c40: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c50: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c60: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3c70: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3c80: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3c90: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3ca0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3cb0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cc0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3cd0: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3ce0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3cf0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d00: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d10: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d20: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d30: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d40: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d50: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d60: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3d70: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3d80: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3d90: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3da0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3db0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3dc0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3dd0: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3de0: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3df0: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e00: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e10: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e20: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e30: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e40: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e50: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e60: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3e70: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3e80: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3e90: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ea0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3eb0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ec0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3ed0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ee0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ef0: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f00: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f20: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f30: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f40: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f60: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3f70: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3f80: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fa0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fb0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3fc0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3fd0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
3fe0: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
3ff0: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4000: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4010: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4020: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4030: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4040: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4050: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4060: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
4070: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
4080: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
40b0: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
40c0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
40d0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
4100: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
4110: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
4120: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
4130: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
4140: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
4150: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4180: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
4190: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
41a0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
41d0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
41e0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
41f0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
4200: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4210: 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  DS: {result code
4220: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4230: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
4240: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
4250: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
4260: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
4270: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65   set shown.** he
4280: 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69  re in order to i
4290: 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20  ndicate success 
42a0: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
42b0: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65  * New error code
42c0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
42d0: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
42e0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
42f0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78  ** See also: [ex
4300: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4310: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a  de definitions].
4320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4330: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30  E_OK           0
4340: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c     /* Successful
4350: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65   result */./* be
4360: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72  ginning-of-error
4370: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e  -codes */.#defin
4380: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
4390: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
43a0: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
43b0: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
43c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
43d0: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
43e0: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20   Internal logic 
43f0: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20  error in SQLite 
4400: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4410: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33  E_PERM         3
4420: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72     /* Access per
4430: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a  mission denied *
4440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4450: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20  _ABORT        4 
4460: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
4470: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
4480: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
4490: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
44a0: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54          5   /* T
44b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
44c0: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
44d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
44e0: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a  KED       6   /*
44f0: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20   A table in the 
4500: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b  database is lock
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  LITE_NOMEM      
4530: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f    7   /* A mallo
4540: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64  c() failed */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
4560: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a  DONLY     8   /*
4570: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   Attempt to writ
4580: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74  e a readonly dat
4590: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
45a0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
45b0: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72  T    9   /* Oper
45c0: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64  ation terminated
45d0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   by sqlite3_inte
45e0: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e  rrupt()*/.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20  e SQLITE_IOERR  
4600: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d       10   /* Som
4610: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49  e kind of disk I
4620: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  /O error occurre
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20  ITE_CORRUPT     
4650: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  11   /* The data
4660: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20  base disk image 
4670: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a  is malformed */.
4680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4690: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20  OTFOUND    12   
46a0: 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64  /* Unknown opcod
46b0: 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c  e in sqlite3_fil
46c0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23  e_control() */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
46e0: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
46f0: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
4700: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
4710: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
4730: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
4740: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
4750: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
4760: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
4770: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
4780: 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   15   /* Databas
4790: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20  e lock protocol 
47a0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
47b0: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20   SQLITE_EMPTY   
47c0: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61      16   /* Data
47d0: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f  base is empty */
47e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47f0: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20  SCHEMA      17  
4800: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4810: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20   schema changed 
4820: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4830: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38  E_TOOBIG      18
4840: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20     /* String or 
4850: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a  BLOB exceeds siz
4860: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69  e limit */.#defi
4870: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
4880: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
4890: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74  ort due to const
48a0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30  E_MISMATCH    20
48d0: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20     /* Data type 
48e0: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66  mismatch */.#def
48f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ine SQLITE_MISUS
4900: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c  E      21   /* L
4910: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f  ibrary used inco
4920: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69  rrectly */.#defi
4930: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20  ne SQLITE_NOLFS 
4940: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73        22   /* Us
4950: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e  es OS features n
4960: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ot supported on 
4970: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  host */.#define 
4980: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20  SQLITE_AUTH     
4990: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f     23   /* Autho
49a0: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20  rization denied 
49b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49c0: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34  E_FORMAT      24
49d0: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20     /* Auxiliary 
49e0: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20  database format 
49f0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
4a00: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4a10: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4a20: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4a30: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4a40: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4a60: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4a70: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4a80: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4a90: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4aa0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4ab0: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4ac0: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4ad0: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4af0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4b00: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4b10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4b60: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4b70: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4b80: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4b90: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4ba0: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4bb0: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4bc0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4be0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4bf0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4c00: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4c10: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4c20: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4c30: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4c40: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4c50: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4c60: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4c70: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4c80: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4c90: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4ca0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4cb0: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4cc0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4cd0: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4ce0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4cf0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4d00: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4d10: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4d20: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4d30: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
4d40: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
4d50: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
4d60: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
4d70: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
4d80: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
4d90: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
4da0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
4db0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
4dc0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
4dd0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
4de0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
4df0: 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65  errors. These [e
4e00: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4e10: 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65  odes] are enable
4e20: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
4e30: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
4e40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
4e50: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
4e60: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
4e70: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
4e80: 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65  )] API.  Or, the
4e90: 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66   extended code f
4ea0: 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  or.** the most r
4eb0: 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20  ecent error can 
4ec0: 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e  be obtained usin
4ed0: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
4ee0: 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
4ef0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
4f00: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4f20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4f30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4f40: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4f50: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4f60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4f70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f80: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4f90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fa0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4fb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4fc0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4fd0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4fe0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4ff0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5000: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
5010: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5020: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
5030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5040: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
5050: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5060: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
5070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5080: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
5090: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50a0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
50b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50c0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
50d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50e0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5100: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5120: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
5130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5140: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
5150: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5160: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
51f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5200: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
5210: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5220: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5240: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
5250: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
5260: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
5270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5280: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
5290: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
52a0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
52b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
52c0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
52d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
52e0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5300: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
5310: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5320: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
5330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5340: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
5350: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5360: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
5370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5380: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
5390: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
53a0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
53b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53c0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
53d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
53e0: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
53f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5400: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5410: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5420: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5430: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5440: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5450: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5460: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5470: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5480: 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20  R_DELETE_NOENT  
5490: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54a0: 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65  R | (23<<8)).#de
54b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
54c0: 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  R_MMAP          
54d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54e0: 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65  R | (24<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5500: 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20  R_GETTEMPPATH   
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5520: 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65  R | (25<<8)).#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5540: 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  R_CONVPATH      
5550: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5560: 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65  R | (26<<8)).#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5580: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
5590: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
55a0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
55c0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
55d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
55e0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
55f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5600: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5610: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5620: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5640: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5650: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5660: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5670: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5680: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5690: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
56a0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
56b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
56d0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
56e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
56f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5700: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5710: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5720: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5730: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5740: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5750: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5760: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5770: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5780: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5790: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57a0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
57b0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
57c0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
57d0: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
57e0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
57f0: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5810: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  ONLY_ROLLBACK   
5820: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5830: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23  ONLY | (3<<8)).#
5840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5850: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20  ADONLY_DBMOVED  
5860: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5870: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29  ADONLY | (4<<8))
5880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5890: 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20  ABORT_ROLLBACK  
58a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
58b0: 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a  ABORT | (2<<8)).
58c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58d0: 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20  ONSTRAINT_CHECK 
58e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
58f0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c  ONSTRAINT | (1<<
5900: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5910: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f  TE_CONSTRAINT_CO
5920: 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49  MMITHOOK   (SQLI
5930: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5940: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5950: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5960: 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28  T_FOREIGNKEY   (
5970: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5980: 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  T | (3<<8)).#def
5990: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
59a0: 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20  RAINT_FUNCTION  
59b0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59c0: 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a  RAINT | (4<<8)).
59d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59e0: 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c  ONSTRAINT_NOTNUL
59f0: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  L      (SQLITE_C
5a00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c  ONSTRAINT | (5<<
5a10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52  TE_CONSTRAINT_PR
5a30: 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49  IMARYKEY   (SQLI
5a40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a50: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
5a60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a70: 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28  T_TRIGGER      (
5a80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a90: 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  T | (7<<8)).#def
5aa0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ab0: 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20  RAINT_UNIQUE    
5ac0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ad0: 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a  RAINT | (8<<8)).
5ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20  ONSTRAINT_VTAB  
5b00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5b10: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c  ONSTRAINT | (9<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f  TE_CONSTRAINT_RO
5b40: 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  WID        (SQLI
5b50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28  TE_CONSTRAINT |(
5b60: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
5b80: 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28  COVER_WAL      (
5b90: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
5bc0: 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28  COVER_ROLLBACK (
5bd0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
5be0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5bf0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41  SQLITE_WARNING_A
5c00: 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28  UTOINDEX       (
5c10: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c  SQLITE_WARNING |
5c20: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5c30: 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45   SQLITE_AUTH_USE
5c40: 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  R               
5c50: 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28  (SQLITE_AUTH | (
5c60: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5c70: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5c80: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5c90: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5ca0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5cb0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5cc0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5cd0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5ce0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5cf0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5d00: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5d10: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5d20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5d30: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5d40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5d50: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5d60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5d70: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5d80: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5d90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5da0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5db0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5dc0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5dd0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5df0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5e00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e10: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5e20: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e40: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5e50: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5e60: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5e70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e80: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5e90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5ea0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5eb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5ec0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5ed0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5ee0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5f10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5f20: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5f30: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5f40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f50: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
5f60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
5f70: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5f80: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5f90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fa0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
5fb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
5fc0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fe0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
5ff0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6000: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6010: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6020: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6030: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6040: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6070: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
60b0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
60f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6130: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
61d0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
61e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6200: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6210: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6220: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6230: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6240: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6250: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6260: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6270: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6280: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6290: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62a0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
62b0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
62c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62d0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
62f0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6300: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6310: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6320: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6330: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6340: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6350: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6360: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6370: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6380: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
6390: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
63a0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
63b0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
63c0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
63d0: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
63e0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
63f0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6400: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6410: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6420: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6430: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6440: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6450: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6460: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6470: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6480: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6490: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
64a0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
64b0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
64c0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
64d0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
64e0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
64f0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6500: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6510: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6520: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6530: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6540: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6550: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6560: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6570: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6580: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6590: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
65a0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
65b0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
65c0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
65d0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
65e0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
65f0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6600: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6610: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6620: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6630: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6640: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6650: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6660: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6670: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6680: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6690: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
66a0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
66b0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
66c0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
66d0: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
66e0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
66f0: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6700: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6710: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6720: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6730: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6740: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6750: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6760: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6770: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6780: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6790: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
67a0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
67b0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
67c0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
67d0: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
67e0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
67f0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a  hen open.  The.*
6800: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
6810: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
6820: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
6830: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6840: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6850: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6860: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6870: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6880: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6890: 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  es..*/.#define S
68a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68b0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
68c0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
68d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68e0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
68f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6900: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
6910: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6920: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
6930: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6970: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
69a0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6aa0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
6ab0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6b10: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
6b20: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6b50: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b90: 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00002000../*.** 
6ba0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6bb0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6bc0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6bd0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6be0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6bf0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6c00: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6c10: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6c20: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6c30: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6c40: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6c50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6c60: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6c70: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6c80: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6c90: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6ca0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6cc0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6cd0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6ce0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6cf0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6d00: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6d10: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6d20: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6d30: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6d40: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6d50: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6d60: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6d70: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6d80: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6d90: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6da0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6db0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6dc0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6dd0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6de0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6df0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6e00: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6e10: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6e20: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6e30: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6e40: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6e50: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6e60: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6e70: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6e80: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6e90: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6ea0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6eb0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6ec0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6ed0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6ee0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6ef0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6f00: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6f10: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6f20: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6f30: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6f40: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6f50: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6f60: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6f70: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6f80: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6f90: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6fa0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6fb0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
6fc0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6fd0: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6fe0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6ff0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
7000: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
7010: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
7020: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
7030: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
7040: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
7050: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7060: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7070: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7080: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7090: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
70a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
70b0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
70c0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
70d0: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
70e0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
70f0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
7100: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
7110: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
7120: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
7130: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
7140: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
7150: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7160: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7170: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7180: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7190: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
71a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
71b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
71c0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
71d0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
71e0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
71f0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7200: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
7210: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
7220: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
7230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7240: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7250: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7260: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7270: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7280: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7290: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
72a0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
72b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
72c0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
72d0: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
72e0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
72f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7300: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7310: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7320: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7330: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7340: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7350: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7360: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7370: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7380: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7390: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
73a0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
73b0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
73c0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
73d0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
73e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
73f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7400: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7410: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7420: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7430: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7440: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7450: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7460: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7470: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7480: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7490: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
74a0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
74b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
74c0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
74d0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
74e0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
74f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7500: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7510: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7520: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7530: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7540: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7550: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7560: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7570: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7580: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7590: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
75a0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
75b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
75c0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
75d0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
75e0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
75f0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7600: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7610: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7620: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7630: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7640: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7650: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7660: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7670: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7680: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7690: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
76a0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
76b0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
76c0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
76d0: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
76e0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
76f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7700: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7710: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7720: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7740: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7750: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7760: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7770: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7780: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7790: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
77a0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
77b0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
77c0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
77d0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
77e0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
77f0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7800: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7810: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7820: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7830: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7840: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7850: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7860: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7870: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7880: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7890: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
78a0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
78b0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
78c0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
78d0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
78e0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
78f0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7900: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
7910: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
7920: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
7930: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7940: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7950: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7960: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7970: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7980: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7990: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
79a0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
79b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
79c0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
79d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
79e0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
79f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7a00: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7a10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7a20: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
7a30: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7a40: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7a50: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7a60: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7a70: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7a80: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7a90: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7aa0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7ab0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7ac0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7ad0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
7ae0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7af0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7b00: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7b10: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
7b20: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
7b30: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7b40: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7b50: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7b60: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7b70: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7b80: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7b90: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7ba0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7bb0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7bc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7bd0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7be0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7bf0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7c10: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7c20: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7c30: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7c40: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7c50: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7c60: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7c70: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7c80: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7c90: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7ca0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7cb0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7cc0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7cd0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7ce0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7cf0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7d00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7d10: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7d20: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7d30: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7d40: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7d50: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7d60: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7d70: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7d80: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7d90: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7da0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7db0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7dc0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7dd0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7de0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7df0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7e00: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7e10: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7e20: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
7e30: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
7e40: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
7e50: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
7e60: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7e70: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7e80: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7e90: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7ea0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7eb0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7ec0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7ed0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7ee0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7ef0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7f00: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
7f10: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
7f20: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7f30: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7f40: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
7f50: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
7f60: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7f70: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7f80: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7f90: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7fa0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7fb0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7fc0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7fd0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7fe0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7ff0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
8000: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
8010: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8020: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8030: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
8040: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
8050: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8060: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8070: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8080: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8090: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
80a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80b0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
80c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
80d0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
80e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80f0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8100: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8110: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8120: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8130: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8140: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8150: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8160: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8170: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8180: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8190: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
81a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81b0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
81c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
81d0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81f0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8200: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
8210: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8220: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
8230: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
8240: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
8250: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8260: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8270: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
8280: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
8290: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
82a0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
82b0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
82c0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
82d0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
82e0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
82f0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
8300: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8310: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8320: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
8330: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
8340: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
8350: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
8360: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
8370: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
8380: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
8390: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
83a0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
83b0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
83c0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
83d0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
83e0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
83f0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
8400: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
8410: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
8420: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
8430: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
8440: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
8450: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
8460: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
8470: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
8480: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
8490: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
84a0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
84b0: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
84c0: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
84d0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
84e0: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
84f0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
8500: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
8510: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8520: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
8530: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
8540: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
8550: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
8560: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8570: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8580: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8590: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
85a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
85b0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
85c0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
85d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85e0: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
85f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8600: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8610: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8620: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8630: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8640: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8650: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8660: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8670: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8680: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8690: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
86a0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
86b0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
86d0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
86e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
86f0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8700: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
8710: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
8720: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8730: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8740: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8750: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8760: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8770: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8780: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8790: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
87a0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
87b0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
87c0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
87d0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
87e0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
87f0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8800: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
8810: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
8820: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8830: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8840: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8850: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8860: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8870: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8880: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8890: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
88a0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
88b0: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
88c0: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
88d0: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
88e0: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
88f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8900: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
8910: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8920: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8930: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8940: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8950: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74  rsion 2 */.  int
8960: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74   (*xFetch)(sqlit
8970: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8980: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69  3_int64 iOfst, i
8990: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a  nt iAmt, void **
89a0: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  pp);.  int (*xUn
89b0: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  fetch)(sqlite3_f
89c0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
89d0: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20  t64 iOfst, void 
89e0: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  *p);.  /* Method
89f0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8a00: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  d for version 3 
8a10: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
8a20: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
8a30: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
8a40: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
8a50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8a60: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
8a70: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
8a80: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69  ** KEYWORDS: {fi
8a90: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
8aa0: 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f  es} {file contro
8ab0: 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  l opcode}.**.** 
8ac0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
8ad0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
8ae0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
8af0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
8b00: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
8b10: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
8b20: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
8b30: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8b40: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
8b50: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
8b60: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8b70: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8b80: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8b90: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8ba0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8bb0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8bc0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8bd0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8be0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8bf0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8c00: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8c10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8c20: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8c30: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8c40: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8c50: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8c60: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8c70: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8c80: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8c90: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8ca0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8cb0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8cc0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8cd0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8ce0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8cf0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8d00: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8d10: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8d20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
8d30: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
8d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8d50: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
8d60: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
8d70: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
8d80: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
8d90: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
8da0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8db0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
8dc0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
8dd0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
8de0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
8df0: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
8e00: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
8e10: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
8e20: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
8e30: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
8e40: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
8e50: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
8e60: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
8e70: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
8e80: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
8e90: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
8ea0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
8eb0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
8ec0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8ed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8ee0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
8ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8f00: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
8f10: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
8f20: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
8f30: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
8f40: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
8f50: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
8f60: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
8f70: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
8f80: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
8f90: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
8fa0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8fb0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
8fc0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
8fd0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
8fe0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
8ff0: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
9000: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
9010: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
9020: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
9030: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
9040: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
9050: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
9060: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
9070: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
9080: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
9090: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
90a0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
90b0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
90c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
90d0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
90e0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
90f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9100: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9110: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9120: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9130: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9140: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9150: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
9160: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9170: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9180: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
9190: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
91a0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
91b0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
91c0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
91d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
91e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
91f0: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c  MITTED]].** No l
9200: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a  onger in use..**
9210: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9220: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a  _FCNTL_SYNC]].**
9230: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9240: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20  TL_SYNC] opcode 
9250: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
9260: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
9270: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f  e and.** sent to
9280: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61   the VFS immedia
9290: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20  tely before the 
92a0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
92b0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20  invoked on a.** 
92c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65  database file de
92d0: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66  scriptor. Or, if
92e0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
92f0: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  d is not invoked
9300: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65   .** because the
9310: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67   user has config
9320: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68  ured SQLite with
9330: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e   .** [PRAGMA syn
9340: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
9350: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
9360: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  F] it is invoked
9370: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66   in place .** of
9380: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
9390: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73  d. In most cases
93a0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72  , the pointer ar
93b0: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69  gument passed wi
93c0: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d  th.** this file-
93d0: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e  control is NULL.
93e0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
93f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
9400: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a  s being synced.*
9410: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d  * as part of a m
9420: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f  ulti-database co
9430: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65  mmit, the argume
9440: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e  nt points to a n
9450: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
9460: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
9470: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ng the transacti
9480: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e  ons master-journ
9490: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46  al file name. VF
94a0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20  Ses that .** do 
94b0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
94c0: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65  gnal should sile
94d0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
94e0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
94f0: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64  tions .** should
9500: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
9510: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9520: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9530: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9540: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20  may .** disrupt 
9550: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
9560: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9570: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9580: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9590: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
95a0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
95b0: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b  SETWO]].** The [
95c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
95d0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70  MIT_PHASETWO] op
95e0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
95f0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9600: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65  SQLite.** and se
9610: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66  nt to the VFS af
9620: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ter a transactio
9630: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69  n has been commi
9640: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  tted immediately
9650: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74  .** but before t
9660: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75  he database is u
9670: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74  nlocked. VFSes t
9680: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  hat do not need 
9690: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73  this signal.** s
96a0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
96b0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
96c0: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
96d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a  should not call.
96e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
96f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9700: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9710: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
9720: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65  rupt the .** ope
9730: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9740: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9750: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9760: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9770: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
9780: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
9790: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
97a0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
97b0: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
97c0: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
97d0: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
97e0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
97f0: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
9800: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
9810: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
9820: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
9830: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
9840: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
9850: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
9860: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
9870: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
9880: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
9890: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
98a0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
98b0: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
98c0: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
98d0: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
98e0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
98f0: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
9900: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
9910: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
9920: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
9930: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
9940: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
9950: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
9960: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
9970: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
9980: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
9990: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
99a0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
99b0: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
99c0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
99d0: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
99e0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
99f0: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
9a00: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
9a10: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
9a20: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
9a30: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
9a40: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
9a50: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
9a60: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
9a70: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
9a80: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
9a90: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
9aa0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
9ab0: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
9ac0: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
9ad0: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
9ae0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
9af0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
9b00: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
9b10: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
9b20: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
9b30: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
9b40: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
9b50: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
9b60: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
9b70: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
9b80: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
9b90: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
9ba0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
9bb0: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
9bc0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9bd0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
9be0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9bf0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9c00: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
9c10: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9c20: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9c30: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
9c40: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
9c50: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
9c60: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
9c70: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
9c80: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
9c90: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
9ca0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
9cb0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
9cc0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
9cd0: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
9ce0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
9cf0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
9d00: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
9d10: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
9d20: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
9d30: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
9d40: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
9d50: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
9d60: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
9d70: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
9d80: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
9d90: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
9da0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
9db0: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
9dc0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9dd0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
9de0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
9df0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
9e00: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
9e10: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9e20: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
9e30: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
9e40: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
9e50: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
9e60: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9e70: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
9e80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9e90: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
9ea0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
9eb0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
9ec0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
9ed0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
9ee0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
9ef0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
9f00: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
9f10: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
9f20: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
9f30: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
9f40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
9f50: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
9f60: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
9f70: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
9f80: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9f90: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9fa0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
9fb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9fc0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9fd0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
9fe0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9ff0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
a000: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
a010: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
a020: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
a030: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
a040: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
a050: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
a060: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a070: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
a080: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
a090: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
a0a0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
a0b0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a0c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a0d0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a0e0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a0f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a100: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a110: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a120: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
a130: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
a140: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
a150: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
a160: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
a170: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
a180: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
a190: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
a1a0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a1b0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
a1c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a1d0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
a1e0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a1f0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a200: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
a210: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
a220: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
a230: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
a240: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
a250: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
a260: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
a270: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
a280: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
a290: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
a2a0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
a2b0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
a2c0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
a2d0: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
a2e0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
a2f0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a300: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
a310: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a320: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
a330: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
a340: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
a350: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
a360: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
a370: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
a380: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
a390: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
a3a0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
a3b0: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
a3c0: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
a3d0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
a3e0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
a3f0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
a400: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
a410: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
a420: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
a430: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
a440: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
a450: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a460: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
a470: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
a480: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
a490: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
a4a0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
a4b0: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
a4c0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
a4d0: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
a4e0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
a4f0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
a500: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
a510: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
a520: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
a530: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
a540: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
a550: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
a560: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
a570: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
a580: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
a590: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
a5a0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
a5b0: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
a5c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a5d0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
a5e0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
a5f0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
a600: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
a610: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a620: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
a630: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
a640: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
a650: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
a660: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
a670: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
a680: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
a690: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
a6a0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
a6b0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
a6c0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
a6d0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a6e0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
a6f0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
a700: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
a710: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
a720: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
a730: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
a740: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
a750: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
a760: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
a770: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
a780: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
a790: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
a7a0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
a7b0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
a7c0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
a7d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a7e0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a7f0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
a800: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
a810: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
a820: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
a830: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
a840: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
a850: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a860: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
a870: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
a880: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
a890: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
a8a0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
a8b0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
a8c0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
a8d0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
a8e0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
a8f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a900: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a910: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a920: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
a930: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
a940: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
a950: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
a960: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a970: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a980: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a990: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
a9a0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
a9b0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
a9c0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
a9d0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
a9e0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
a9f0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
aa00: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
aa10: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66   statement.  ^If
aa20: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
aa30: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
aa40: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
aa50: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
aa60: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
aa70: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
aa80: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
aa90: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
aaa0: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
aab0: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
aac0: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
aad0: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
aae0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
aaf0: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
ab00: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
ab10: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
ab20: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ab30: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
ab40: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
ab50: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
ab60: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
ab70: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
ab80: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
ab90: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
aba0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
abb0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
abc0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
abd0: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
abe0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
abf0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a  TL_BUSYHANDLER].
ac00: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
ac10: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62  may be invoked b
ac20: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20  y SQLite on the 
ac30: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
ac40: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20  ndle.** shortly 
ac50: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e  after it is open
ac60: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  ed in order to p
ac70: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20  rovide a custom 
ac80: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a  VFS with access.
ac90: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63  ** to the connec
aca0: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c  tions busy-handl
acb0: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65  er callback. The
acc0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20   argument is of 
acd0: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a  type (void **).*
ace0: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20  * - an array of 
acf0: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c  two (void *) val
ad00: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28  ues. The first (
ad10: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79  void *) actually
ad20: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
ad30: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
ad40: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a   (int (*)(void *
ad50: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  )). In order to 
ad60: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65  invoke the conne
ad70: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68  ctions.** busy-h
ad80: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e  andler, this fun
ad90: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ction should be 
ada0: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
adb0: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29   second (void *)
adc0: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79   in.** the array
add0: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67   as the only arg
ade0: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74  ument. If it ret
adf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
ae00: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f  hen the operatio
ae10: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
ae20: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65  etried. If it re
ae30: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
ae40: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c  custom VFS shoul
ae50: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a  d abandon the.**
ae60: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
ae70: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
ae80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
ae90: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  PFILENAME]].** ^
aea0: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  Application can 
aeb0: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49  invoke the [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
aed0: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74  ENAME] file-cont
aee0: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53  rol.** to have S
aef0: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
af00: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
af10: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
af20: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
af30: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
af40: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
af50: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
af60: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
af70: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
af80: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
af90: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
afa0: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
afb0: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
afc0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
afd0: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
afe0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
aff0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b000: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
b010: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
b020: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
b030: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
b040: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
b050: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
b060: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  eak..**.** <li>[
b070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b080: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  AP_SIZE]].** The
b090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
b0a0: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
b0b0: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74  ontrol is used t
b0c0: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74  o query or set t
b0d0: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75  he.** maximum nu
b0e0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68  mber of bytes th
b0f0: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  at will be used 
b100: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  for memory-mappe
b110: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72  d I/O..** The ar
b120: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
b130: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
b140: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
b150: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20  nt64 that.** is 
b160: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69  an advisory maxi
b170: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b180: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20  tes in the file 
b190: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20  to memory map.  
b1a0: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  The.** pointer i
b1b0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
b1c0: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65  th the old value
b1d0: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  .  The limit is 
b1e0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a  not changed if.*
b1f0: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67  * the value orig
b200: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74  inally pointed t
b210: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  o is negative, a
b220: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e  nd so the curren
b230: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20  t limit .** can 
b240: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61  be queried by pa
b250: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74  ssing in a point
b260: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  er to a negative
b270: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a   number.  This.*
b280: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  * file-control i
b290: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
b2a0: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  y to implement [
b2b0: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
b2c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
b2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b2e0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b2f0: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  TE_FCNTL_TRACE] 
b300: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f  file control pro
b310: 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69  vides advisory i
b320: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f  nformation.** to
b330: 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77   the VFS about w
b340: 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c  hat the higher l
b350: 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c  ayers of the SQL
b360: 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f  ite stack are do
b370: 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c  ing..** This fil
b380: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b390: 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63  d by some VFS ac
b3a0: 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b  tivity tracing [
b3b0: 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  shims]..** The a
b3c0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72  rgument is a zer
b3d0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
b3e0: 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79  ing.  Higher lay
b3f0: 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51  ers in the.** SQ
b400: 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67  Lite stack may g
b410: 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65  enerate instance
b420: 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63  s of this file c
b430: 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65  ontrol if.** the
b440: 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e   [SQLITE_USE_FCN
b450: 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  TL_TRACE] compil
b460: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
b470: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
b480: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b490: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a  TL_HAS_MOVED]].*
b4a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b4b0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66  NTL_HAS_MOVED] f
b4c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  ile control inte
b4d0: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
b4e0: 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e  ent as a.** poin
b4f0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
b500: 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20  r and it writes 
b510: 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74  a boolean into t
b520: 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65  hat integer depe
b530: 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74  nding.** on whet
b540: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
b550: 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e  ile has been ren
b560: 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20  amed, moved, or 
b570: 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74  deleted since it
b580: 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70  .** was first op
b590: 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ened..**.** <li>
b5a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
b5b0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
b5c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b5d0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
b5e0: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
b5f0: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
b600: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
b610: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
b620: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
b630: 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68  ethod to swap th
b640: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69  e file handle wi
b650: 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f  th the one.** po
b660: 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
b670: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20  pArg argument.  
b680: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20  This capability 
b690: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
b6a0: 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e  esting.** and on
b6b0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
b6c0: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
b6d0: 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66  LITE_TEST is def
b6e0: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c  ined..**.** </ul
b6f0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
b700: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
b710: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
b720: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
b730: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
b740: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
b750: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
b760: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
b770: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
b780: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
b790: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
b7a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
b7b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b7c0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
b7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
b7e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7f0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
b800: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
b810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b820: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
b830: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
b840: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b850: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
b860: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
b870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b880: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
b890: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
b8a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b8b0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
b8c0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
b8d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b8e0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
b8f0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
b900: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
b910: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
b920: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
b930: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
b940: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
b950: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
b960: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b970: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
b980: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
b990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b9a0: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
b9b0: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
b9c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b9d0: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
b9e0: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
b9f0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
ba00: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
ba10: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
ba20: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
ba30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ba40: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
ba50: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
ba60: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
ba70: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
ba80: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
ba90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
baa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bab0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
bac0: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
bad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bae0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
baf0: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 0a  ANDLE       23..
bb00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bb10: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
bb20: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
bb30: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
bb40: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
bb50: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
bb60: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
bb70: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
bb80: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
bb90: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
bba0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
bbb0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
bbc0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
bbd0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
bbe0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
bbf0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
bc00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
bc10: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
bc20: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
bc30: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
bc40: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
bc50: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
bc60: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bc70: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
bc80: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
bc90: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
bca0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
bcb0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
bcc0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
bcd0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
bce0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
bcf0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
bd00: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
bd10: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
bd20: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
bd30: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
bd40: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
bd50: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
bd60: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
bd70: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
bd80: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
bd90: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
bda0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
bdb0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
bdc0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
bdd0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
bde0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
bdf0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
be00: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
be10: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
be20: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
be30: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
be40: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
be50: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
be60: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
be70: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
be80: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
be90: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
bea0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
beb0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
bec0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
bed0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
bee0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
bef0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
bf00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
bf10: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
bf20: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
bf30: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
bf40: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
bf50: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
bf60: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
bf70: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
bf80: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
bf90: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
bfa0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
bfb0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
bfc0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
bfd0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
bfe0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
bff0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
c000: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
c010: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
c020: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
c030: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
c040: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
c050: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
c060: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
c070: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
c080: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
c090: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
c0a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
c0b0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
c0c0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
c0d0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
c0e0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
c0f0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
c100: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
c110: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
c120: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
c130: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
c140: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
c150: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
c160: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
c170: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
c180: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
c190: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
c1a0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
c1b0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
c1c0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
c1d0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
c1e0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
c1f0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c200: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
c210: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
c220: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
c230: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
c240: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
c250: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
c260: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
c270: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
c280: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
c290: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
c2a0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
c2b0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
c2c0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
c2d0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
c2e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
c2f0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
c300: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
c310: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c320: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
c330: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
c340: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
c350: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
c360: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
c370: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
c380: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
c390: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
c3a0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
c3b0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c3c0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
c3d0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
c3e0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
c3f0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
c400: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
c410: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
c420: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
c430: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
c440: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
c450: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
c460: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
c470: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
c480: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
c490: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
c4a0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
c4b0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
c4c0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
c4d0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
c4e0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
c4f0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
c500: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
c510: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
c520: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
c530: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
c540: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c550: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c560: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
c570: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
c580: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
c590: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
c5a0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
c5b0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
c5c0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
c5d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
c5e0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
c5f0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
c600: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
c610: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
c620: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
c630: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
c640: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
c650: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
c660: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
c670: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
c680: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
c690: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
c6a0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
c6b0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
c6c0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
c6d0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
c6e0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
c6f0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
c700: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
c710: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
c720: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
c730: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
c740: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
c750: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
c760: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
c770: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
c780: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
c790: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
c7a0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
c7b0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
c7c0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
c7d0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
c7e0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
c7f0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
c800: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
c810: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
c820: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
c830: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
c840: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c850: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
c860: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c870: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
c880: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c890: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
c8a0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c8b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
c8c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
c8d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
c8e0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
c8f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c900: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
c910: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c920: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
c930: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c940: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
c950: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
c960: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
c970: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
c980: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
c990: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
c9a0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
c9b0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
c9c0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
c9d0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
c9e0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
c9f0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
ca00: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
ca10: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
ca20: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
ca30: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
ca40: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
ca50: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
ca60: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
ca70: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
ca80: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
ca90: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
caa0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
cab0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
cac0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
cad0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
cae0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
caf0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
cb00: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
cb10: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
cb20: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
cb30: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
cb40: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
cb50: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
cb60: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
cb70: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
cb80: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
cb90: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
cba0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
cbb0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
cbc0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
cbd0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cbe0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
cbf0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cc00: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
cc10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
cc20: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cc30: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
cc40: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
cc50: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
cc60: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
cc70: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
cc80: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cc90: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
cca0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
ccb0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
ccc0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
ccd0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
cce0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
ccf0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
cd00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
cd10: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
cd20: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
cd30: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
cd40: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
cd50: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
cd60: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
cd70: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
cd80: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
cd90: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
cda0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
cdb0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
cdc0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
cdd0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
cde0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
cdf0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
ce00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
ce10: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
ce20: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
ce30: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
ce40: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
ce50: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
ce60: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
ce70: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
ce80: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
ce90: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
cea0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
ceb0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
cec0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
ced0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
cee0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
cef0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
cf00: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
cf10: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
cf20: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
cf30: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
cf40: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
cf50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
cf60: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
cf70: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
cf80: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
cf90: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
cfa0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
cfb0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
cfc0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
cfd0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
cfe0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
cff0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
d000: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
d010: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
d020: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
d030: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
d040: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
d050: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
d060: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
d070: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
d080: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d090: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
d0a0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
d0b0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
d0c0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
d0d0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
d0e0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
d0f0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
d100: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
d110: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
d120: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
d130: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
d140: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
d150: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
d160: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
d170: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
d180: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
d190: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d1a0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
d1b0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
d1c0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
d1d0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
d1e0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d1f0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
d200: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
d210: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
d220: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
d230: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
d240: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
d250: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
d260: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
d270: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
d280: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
d290: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
d2a0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
d2b0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
d2c0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d2d0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
d2e0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
d2f0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
d300: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
d310: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d320: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
d330: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
d340: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
d350: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
d360: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
d370: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
d380: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
d390: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
d3a0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
d3b0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
d3c0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
d3d0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
d3e0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
d3f0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
d400: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d410: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
d420: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
d430: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d440: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
d450: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
d460: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
d470: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
d480: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
d490: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
d4a0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
d4b0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
d4c0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d4d0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
d4e0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
d4f0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
d500: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
d510: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
d520: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
d530: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
d540: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
d550: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
d560: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
d570: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
d580: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
d590: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
d5a0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
d5b0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
d5c0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
d5d0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
d5e0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
d5f0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
d600: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
d610: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
d620: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
d630: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
d640: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
d650: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
d660: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
d670: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
d680: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
d690: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
d6a0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
d6b0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
d6c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
d6d0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
d6e0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
d6f0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
d700: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
d710: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
d720: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
d730: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
d740: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
d750: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
d760: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
d770: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
d780: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
d790: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
d7a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
d7b0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
d7c0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
d7d0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
d7e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
d7f0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
d800: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
d810: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
d820: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
d830: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
d840: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
d850: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
d860: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
d870: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
d880: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
d890: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
d8a0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
d8b0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
d8c0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
d8d0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
d8e0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
d8f0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
d900: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
d910: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
d920: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
d930: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
d940: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
d950: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
d960: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
d970: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
d980: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
d990: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
d9a0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
d9b0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
d9c0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
d9d0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
d9e0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
d9f0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
da00: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
da10: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
da20: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
da30: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
da40: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
da50: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
da60: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
da70: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
da80: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
da90: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
daa0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
dab0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
dac0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
dad0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
dae0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
daf0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
db00: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
db10: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
db20: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
db30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
db40: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
db50: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
db60: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
db70: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
db80: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
db90: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
dba0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
dbb0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
dbc0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
dbd0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
dbe0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
dbf0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
dc00: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
dc10: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
dc20: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
dc30: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
dc40: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
dc50: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
dc60: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
dc70: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
dc80: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
dc90: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
dca0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
dcb0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
dcc0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
dcd0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
dce0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
dcf0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
dd00: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
dd10: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
dd20: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
dd30: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
dd40: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
dd50: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
dd60: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
dd70: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
dd80: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
dd90: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
dda0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ddb0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
ddc0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
ddd0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
dde0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ddf0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
de00: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
de10: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
de20: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
de30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
de40: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
de50: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
de60: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
de70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
de80: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
de90: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
dea0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
deb0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
dec0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
ded0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
dee0: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
def0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
df00: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
df10: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
df20: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
df30: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
df40: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
df50: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
df60: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
df70: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
df80: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
df90: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
dfa0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
dfb0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
dfc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
dfd0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
dfe0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
dff0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e000: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
e010: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e020: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e030: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
e040: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e050: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
e060: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
e070: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
e080: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
e090: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
e0a0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
e0b0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
e0c0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
e0d0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
e0e0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e0f0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e100: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
e110: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e120: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
e130: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
e140: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
e150: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
e160: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
e170: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e180: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e190: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e1a0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
e1b0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
e1c0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
e1d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e1e0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
e1f0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
e200: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
e210: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e220: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e230: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
e240: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e250: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e260: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
e270: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e280: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
e290: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
e2a0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
e2b0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
e2c0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
e2d0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
e2e0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
e2f0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
e300: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e310: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
e320: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
e330: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
e340: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
e350: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
e360: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
e370: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
e380: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
e390: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
e3a0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
e3b0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
e3c0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
e3d0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
e3e0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
e3f0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
e400: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e410: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
e420: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
e430: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
e440: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
e450: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
e460: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e470: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
e480: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
e490: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
e4a0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
e4b0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
e4c0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
e4d0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
e4e0: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
e4f0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
e500: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
e510: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
e520: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
e530: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e540: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
e550: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
e560: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
e570: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
e580: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
e590: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
e5a0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
e5b0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
e5c0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
e5d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e5e0: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
e5f0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
e600: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
e610: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
e620: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e630: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
e640: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
e650: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
e660: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
e670: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
e680: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
e690: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
e6a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
e6b0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
e6c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e6d0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
e6e0: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
e6f0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
e700: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
e710: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e720: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
e730: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
e740: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
e750: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
e760: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
e770: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
e780: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
e790: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
e7a0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
e7b0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
e7c0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e7d0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
e7e0: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
e7f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
e800: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
e810: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
e820: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
e830: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
e840: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
e850: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
e860: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e870: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e880: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
e890: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e8a0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
e8b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e8c0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e8d0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e8e0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e8f0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e900: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
e910: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
e920: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
e930: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
e940: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
e950: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
e960: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
e970: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
e980: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
e990: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e9a0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
e9b0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
e9c0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
e9d0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
e9e0: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
e9f0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
ea00: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
ea10: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
ea20: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
ea30: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
ea40: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
ea50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ea60: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
ea70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ea80: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
ea90: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
eaa0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
eab0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
eac0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
ead0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
eae0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
eaf0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
eb00: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
eb10: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
eb20: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
eb30: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
eb40: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
eb50: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
eb60: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
eb70: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
eb80: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
eb90: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
eba0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
ebb0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
ebc0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
ebd0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
ebe0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
ebf0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
ec00: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
ec10: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
ec20: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
ec30: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
ec40: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
ec50: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
ec60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
ec70: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
ec80: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
ec90: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
eca0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
ecb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
ecc0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
ecd0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
ece0: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
ecf0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
ed00: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
ed10: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
ed20: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
ed30: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
ed40: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
ed50: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
ed60: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
ed70: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
ed80: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
ed90: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
eda0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
edb0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
edc0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
edd0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
ede0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
edf0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
ee00: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
ee10: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
ee20: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
ee30: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
ee40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ee50: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
ee60: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
ee70: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ee80: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
ee90: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
eea0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
eeb0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
eec0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
eed0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
eee0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
eef0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
ef00: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
ef10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ef20: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
ef30: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
ef40: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
ef50: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
ef60: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ef70: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
ef80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ef90: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
efa0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
efb0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
efc0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
efd0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
efe0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
eff0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
f000: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f010: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
f020: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
f030: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f040: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
f050: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
f060: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
f070: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
f080: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
f090: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
f0a0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
f0b0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
f0c0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
f0d0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
f0e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f0f0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
f100: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
f110: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
f120: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
f130: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
f140: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
f150: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f160: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
f170: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
f180: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f190: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
f1a0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f1b0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
f1c0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f1d0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
f1e0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f1f0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
f200: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f210: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
f220: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
f230: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
f240: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
f250: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
f260: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
f270: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
f280: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
f290: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
f2a0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
f2b0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
f2c0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
f2d0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
f2e0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
f2f0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
f300: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
f310: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f320: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f330: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
f340: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
f350: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
f360: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
f370: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
f380: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
f390: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
f3a0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
f3b0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
f3c0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
f3d0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
f3e0: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
f3f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f400: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
f410: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
f420: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
f430: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
f440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f450: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
f460: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
f470: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
f480: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
f490: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
f4a0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
f4b0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
f4c0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
f4d0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
f4e0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
f4f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f500: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f510: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
f520: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
f530: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
f540: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f550: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
f560: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
f570: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
f580: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
f590: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
f5a0: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
f5b0: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
f5c0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
f5d0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f5e0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
f5f0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
f600: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
f610: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f620: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
f630: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
f640: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
f650: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
f660: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
f670: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
f680: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
f690: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
f6a0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
f6b0: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
f6c0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
f6d0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
f6e0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f6f0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
f700: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
f710: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
f720: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
f730: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
f740: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f750: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
f760: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
f770: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
f780: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
f790: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
f7a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
f7b0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
f7c0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
f7d0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
f7e0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
f7f0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
f800: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
f810: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
f820: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
f830: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
f840: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
f850: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
f860: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
f870: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
f880: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
f890: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
f8a0: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
f8b0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
f8c0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
f8d0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
f8e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
f8f0: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
f900: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
f910: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f920: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
f930: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
f940: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
f950: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f960: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
f970: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
f980: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
f990: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
f9a0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f9b0: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
f9c0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
f9d0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
f9e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f9f0: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
fa00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
fa10: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
fa20: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
fa30: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
fa40: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
fa50: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
fa60: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
fa70: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
fa80: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
fa90: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
faa0: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
fab0: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
fac0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
fad0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
fae0: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
faf0: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
fb00: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
fb10: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
fb20: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
fb30: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fb40: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
fb50: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
fb60: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
fb70: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fb80: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
fb90: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
fba0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
fbb0: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
fbc0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
fbd0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
fbe0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
fbf0: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
fc00: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
fc10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fc20: 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
fc30: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
fc40: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
fc50: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
fc60: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fc70: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
fc80: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
fc90: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
fca0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
fcb0: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
fcc0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
fcd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fce0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fcf0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
fd00: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
fd10: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
fd20: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
fd30: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
fd40: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
fd50: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
fd60: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
fd70: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
fd80: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
fd90: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
fda0: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
fdb0: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
fdc0: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
fdd0: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
fde0: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
fdf0: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
fe00: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
fe10: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
fe20: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
fe30: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fe40: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
fe50: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
fe60: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
fe70: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
fe80: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
fe90: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
fea0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
feb0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
fec0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
fed0: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
fee0: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
fef0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
ff00: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
ff10: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
ff20: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
ff30: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
ff40: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
ff50: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
ff60: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
ff70: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ff80: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
ff90: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
ffa0: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
ffb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
ffc0: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
ffd0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ffe0: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
fff0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
10000 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
10010 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
10020 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10030 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
10040 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
10050 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
10060 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
10070 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
10080 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
10090 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
100a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
100b0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
100c0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
100d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
100e0 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
100f0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
10100 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
10110 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
10120 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
10130 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
10140 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
10150 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
10160 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
10170 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10180 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
10190 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
101a0 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
101b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
101c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
101d0 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
101e0 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
101f0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
10200 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
10210 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
10220 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
10230 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
10240 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
10250 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
10260 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
10270 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
10280 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10290 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
102a0 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
102b0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
102c0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
102d0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
102e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
102f0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
10300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10310 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
10320 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10330 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10340 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
10350 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
10360 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
10370 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
10380 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
10390 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
103a0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
103b0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
103c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
103d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
103e0 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
103f0 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
10400 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
10410 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10420 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
10430 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
10440 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
10450 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
10460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10470 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
10480 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
10490 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
104a0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
104b0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
104c0 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
104d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
104e0 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
104f0 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
10500 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
10510 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
10520 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
10530 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
10540 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
10550 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
10560 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
10570 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10580 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
10590 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
105a0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
105b0 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
105c0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
105d0 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
105e0 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
105f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10600 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
10610 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
10620 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
10630 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
10640 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10650 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
10660 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
10670 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
10680 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
10690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
106a0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
106b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
106c0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
106d0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
106e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
106f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
10700 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
10710 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
10720 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
10730 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
10740 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
10750 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
10760 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
10770 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10780 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
10790 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
107a0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
107b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
107c0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
107d0 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
107e0 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
107f0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
10800 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
10810 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
10820 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
10830 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
10840 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
10850 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
10860 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
10870 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
10880 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
10890 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
108a0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
108b0 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
108c0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
108d0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
108e0 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
108f0 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
10900 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
10910 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
10920 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
10930 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
10940 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
10950 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
10960 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10970 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10980 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
10990 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
109a0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
109b0 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
109c0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
109d0 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
109e0 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
109f0 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
10a00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
10a10 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
10a20 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
10a30 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
10a40 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
10a50 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
10a60 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
10a70 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
10a80 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
10a90 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
10aa0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
10ab0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
10ac0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
10ad0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
10ae0 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
10af0 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
10b00 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
10b10 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
10b20 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
10b30 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
10b40 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
10b50 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
10b60 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
10b70 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
10b80 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
10b90 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
10ba0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
10bb0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
10bc0 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
10bd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
10be0 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
10bf0 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
10c00 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
10c10 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
10c20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
10c30 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
10c40 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
10c50 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
10c60 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
10c70 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
10c80 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
10c90 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
10ca0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
10cb0 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
10cc0 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
10cd0 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
10ce0 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
10cf0 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
10d00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
10d10 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
10d20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
10d30 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
10d40 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
10d50 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
10d60 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
10d70 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
10d80 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
10d90 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
10da0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
10db0 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
10dc0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
10dd0 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
10de0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
10df0 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
10e00 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
10e10 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
10e20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
10e30 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
10e40 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
10e50 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
10e60 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10e70 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
10e80 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
10e90 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10ea0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
10eb0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
10ec0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
10ed0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
10ee0 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
10ef0 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
10f00 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
10f10 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
10f20 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
10f30 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
10f40 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
10f50 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
10f60 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
10f70 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
10f80 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
10f90 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10fa0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
10fb0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
10fc0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10fd0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
10fe0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
10ff0 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
11000 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
11010 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11020 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11030 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11040 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11050 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11060 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
11070 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
11080 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11090 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
110a0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
110b0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
110c0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
110d0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
110e0 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
110f0 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
11100 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
11110 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11120 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11130 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11140 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11150 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11160 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11170 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
11180 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
11190 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
111a0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
111b0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
111c0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
111d0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
111e0 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
111f0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
11200 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
11210 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
11220 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11230 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
11240 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
11250 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11260 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
11270 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
11280 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
11290 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
112a0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
112b0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
112c0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
112d0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
112e0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
112f0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
11300 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
11310 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
11320 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11330 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
11340 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
11350 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
11360 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
11370 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
11380 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11390 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
113a0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
113b0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
113c0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
113d0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
113e0 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
113f0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11400 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
11410 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
11420 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
11430 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11440 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11450 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
11460 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
11470 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
11480 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
11490 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
114a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
114b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
114c0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
114d0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
114e0 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
114f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
11500 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
11510 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
11520 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
11530 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
11540 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
11550 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
11560 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11570 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
11580 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
11590 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
115a0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
115b0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
115c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
115d0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
115e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
115f0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
11600 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
11610 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
11620 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
11630 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
11640 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
11650 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
11660 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
11670 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
11680 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
11690 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
116a0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
116b0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
116c0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
116d0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
116e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
116f0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
11700 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
11710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11720 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
11730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11740 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
11750 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
11760 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11770 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11780 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11790 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
117a0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
117b0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
117c0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
117d0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
117e0 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
117f0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
11800 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
11810 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
11820 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
11830 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
11840 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11850 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11860 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11870 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11880 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11890 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
118a0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
118b0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
118c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
118d0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
118e0 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
118f0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
11900 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
11910 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
11920 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
11930 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11940 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
11950 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11960 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
11970 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11980 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11990 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
119a0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
119b0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
119c0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
119d0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
119e0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
119f0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11a00 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11a10 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11a20 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
11a30 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
11a40 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
11a50 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
11a60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11a70 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11a80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11a90 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
11aa0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
11ab0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
11ac0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
11ad0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11ae0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11af0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11b00 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
11b10 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
11b20 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
11b30 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
11b40 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
11b50 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
11b60 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11b70 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
11b80 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
11b90 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
11ba0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11bb0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
11bc0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
11bd0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11be0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11bf0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11c00 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11c10 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11c20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11c30 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
11c40 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
11c50 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
11c60 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11c70 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11c80 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11c90 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11ca0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11cb0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11cc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11cd0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
11ce0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11cf0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11d00 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11d10 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
11d20 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11d30 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11d40 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11d50 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11d60 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11d70 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11d80 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11d90 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
11da0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11db0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
11dc0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
11dd0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
11de0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
11df0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
11e00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
11e10 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11e20 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
11e30 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
11e40 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
11e50 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
11e60 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11e70 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
11e80 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
11e90 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11ea0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
11eb0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
11ec0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
11ed0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11ee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11ef0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
11f00 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
11f10 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
11f20 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
11f30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
11f40 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
11f50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11f60 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
11f70 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
11f80 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
11f90 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11fa0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11fb0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11fc0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11fd0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11fe0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11ff0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12000 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12010 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12020 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12030 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12040 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12050 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12060 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12070 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12080 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12090 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
120a0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
120b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
120c0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
120d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
120e0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
120f0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12100 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12110 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12120 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12130 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
12140 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12150 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12160 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
12170 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
12180 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
12190 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
121a0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
121b0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
121c0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
121d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
121e0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
121f0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
12200 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
12210 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
12220 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
12230 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12240 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12250 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
12260 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
12270 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
12280 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
12290 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
122a0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
122b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
122c0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
122d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
122e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
122f0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12300 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12310 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12320 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12330 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12340 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
12350 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12360 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12370 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12380 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12390 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
123a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
123b0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
123c0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
123d0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
123e0 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
123f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12400 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12410 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
12420 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
12430 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
12440 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
12450 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
12460 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
12470 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12480 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12490 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
124a0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
124b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
124c0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
124d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
124e0 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
124f0 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
12500 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
12510 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
12520 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
12530 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
12540 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
12550 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
12560 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12570 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
12580 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
12590 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
125a0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
125b0 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
125c0 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
125d0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
125e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
125f0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12600 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
12610 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
12620 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
12630 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
12640 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12650 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
12660 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
12670 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12680 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
12690 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
126a0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
126b0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
126c0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
126d0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
126e0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
126f0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12700 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12710 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
12720 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
12730 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12740 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
12750 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12760 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
12770 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
12780 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
12790 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
127a0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
127b0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
127c0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
127d0 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
127e0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
127f0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
12800 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
12810 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
12820 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
12830 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
12840 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
12850 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
12860 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
12870 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
12880 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
12890 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
128a0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
128b0 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
128c0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
128d0 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
128e0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
128f0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12900 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
12910 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
12920 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
12930 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12940 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
12950 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
12960 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
12970 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
12980 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
12990 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
129a0 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
129b0 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
129c0 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
129d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
129e0 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
129f0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
12a00 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
12a10 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
12a20 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
12a30 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
12a40 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
12a50 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
12a60 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
12a70 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
12a80 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
12a90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
12aa0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
12ab0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
12ac0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
12ad0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12ae0 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12af0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12b00 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
12b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12b20 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
12b30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12b40 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12b50 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12b60 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12b70 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
12b80 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12b90 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
12ba0 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
12bb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12bc0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
12bd0 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12be0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12bf0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12c00 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
12c10 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12c20 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
12c30 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
12c40 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
12c50 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
12c60 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12c70 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12c80 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
12c90 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
12ca0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
12cb0 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
12cc0 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
12cd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12ce0 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12cf0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12d00 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
12d10 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
12d20 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
12d30 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
12d40 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
12d50 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
12d60 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12d70 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
12d80 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
12d90 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
12da0 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
12db0 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
12dc0 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
12dd0 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12de0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12df0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12e00 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
12e10 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
12e20 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
12e30 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
12e40 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
12e50 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
12e60 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12e70 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
12e80 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
12e90 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
12ea0 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
12eb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
12ec0 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
12ed0 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12ee0 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12ef0 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12f00 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
12f10 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
12f20 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
12f30 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
12f40 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12f50 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
12f60 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12f70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
12f80 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
12f90 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
12fa0 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
12fb0 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
12fc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12fd0 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12fe0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12ff0 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
13000 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
13010 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
13020 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
13030 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13040 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13050 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13060 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13070 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13080 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13090 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
130a0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
130b0 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
130c0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
130d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
130e0 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
130f0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
13100 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
13110 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
13120 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
13130 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
13140 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
13150 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
13160 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13170 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
13180 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
13190 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
131a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
131b0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
131c0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
131d0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
131e0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
131f0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
13200 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
13210 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
13220 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
13230 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
13240 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
13250 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
13260 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
13270 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
13280 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
13290 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
132a0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
132b0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
132c0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
132d0 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
132e0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
132f0 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
13300 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13310 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
13320 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
13330 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
13340 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
13350 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
13360 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
13370 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13380 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
13390 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
133a0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
133b0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
133c0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
133d0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
133e0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
133f0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
13400 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
13410 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13420 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
13430 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
13440 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
13450 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
13460 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13470 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
13480 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
13490 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
134a0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
134b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
134c0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
134d0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
134e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
134f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13500 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13510 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13520 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
13530 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
13540 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
13550 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
13560 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
13570 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
13580 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
13590 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
135a0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
135b0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
135c0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
135d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
135e0 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
135f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13600 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13610 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
13620 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
13630 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13640 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
13650 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13660 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13670 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13680 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
13690 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
136a0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
136b0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
136c0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
136d0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
136e0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
136f0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
13700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13710 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
13720 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13730 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13740 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
13750 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
13760 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
13770 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13780 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
13790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
137a0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
137b0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
137c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
137d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
137e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
137f0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
13810 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
13820 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
13830 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
13840 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
13850 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
13860 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13870 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
13880 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13890 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
138a0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
138b0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
138c0 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
138d0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
138e0 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
138f0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
13900 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
13910 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
13920 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
13930 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
13940 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13950 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13960 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13970 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13980 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13990 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
139a0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
139b0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
139c0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
139d0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
139e0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
139f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13a00 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
13a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13a20 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
13a30 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13a40 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13a50 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13a60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13a70 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13a80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13a90 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
13aa0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13ab0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13ac0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
13ad0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13ae0 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13af0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13b00 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
13b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13b20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
13b30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13b40 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
13b50 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
13b60 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13b70 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
13b80 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
13b90 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
13ba0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
13bb0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
13bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13bd0 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13be0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13bf0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13c00 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
13c10 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
13c20 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
13c30 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
13c40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13c50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
13c60 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13c70 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
13c80 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
13c90 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
13ca0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13cc0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13cd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13ce0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13cf0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13d00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13d10 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13d20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
13d30 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13d40 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13d50 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
13d60 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13d70 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
13d80 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
13d90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13da0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13db0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
13dc0 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
13dd0 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13de0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13df0 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13e00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13e10 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
13e20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13e30 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
13e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13e50 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13e60 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13e70 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13e80 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
13e90 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13ea0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
13eb0 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
13ec0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
13ed0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13ee0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13ef0 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13f00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13f10 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
13f20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13f30 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
13f40 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
13f50 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
13f60 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
13f70 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
13f80 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
13f90 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
13fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13fb0 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
13fc0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
13fd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
13fe0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
13ff0 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
14000 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
14010 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
14020 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
14030 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
14040 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
14050 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
14060 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
14070 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
14080 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
14090 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
140a0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
140b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
140c0 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
140d0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
140e0 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
140f0 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
14100 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
14110 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
14120 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
14130 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14140 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
14150 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
14160 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14170 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14180 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
14190 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
141a0 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
141b0 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
141c0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
141d0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
141e0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
141f0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
14200 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14210 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
14220 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
14230 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
14240 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
14250 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
14260 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
14270 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
14280 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
14290 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
142a0 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
142b0 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
142c0 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
142d0 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
142e0 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
142f0 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
14300 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
14310 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
14320 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14330 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
14340 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
14350 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
14360 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
14370 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
14380 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
14390 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
143a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
143b0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
143c0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
143d0 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
143e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
143f0 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
14400 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
14410 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73  RI.** <dd>^(This
14420 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14430 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14440 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
14450 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
14460 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
14470 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
14480 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
14490 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
144a0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
144b0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
144c0 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
144d0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
144e0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
144f0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
14500 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
14510 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
14520 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
14530 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
14540 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
14550 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
14560 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
14570 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
14580 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
14590 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
145a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
145b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
145c0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
145d0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
145e0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
145f0 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
14600 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
14610 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
14620 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
14630 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
14640 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
14650 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
14660 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
14670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14680 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
14690 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
146a0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
146b0 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
146c0 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
146d0 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
146e0 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
146f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
14700 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
14710 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
14720 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14730 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
14740 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
14750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
14760 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14770 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14780 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14790 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75  gle integer argu
147a0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
147b0 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20  terpreted as.** 
147c0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
147d0 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
147e0 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
147f0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14800 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20  ces for.** full 
14810 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
14820 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
14830 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  er.  ^The defaul
14840 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
14850 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
14860 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14870 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14880 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14890 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
148a0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
148b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
148c0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
148d0 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
148e0 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
148f0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14900 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
14910 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
14920 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
14930 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
14940 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
14950 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
14960 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14970 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14980 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14990 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
149a0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
149b0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
149c0 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
149d0 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
149e0 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
149f0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14a00 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
14a10 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
14a20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
14a30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14a40 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
14a50 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14a60 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14a70 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14a80 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14a90 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14aa0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14ab0 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14ac0 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14ad0 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14ae0 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14af0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14b00 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
14b10 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
14b20 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
14b30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14b40 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
14b50 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14b60 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
14b70 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
14b80 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14b90 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
14ba0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
14bb0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14bc0 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
14bd0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
14be0 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
14bf0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
14c00 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
14c10 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
14c20 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
14c30 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
14c40 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
14c50 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
14c60 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
14c70 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
14c80 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14c90 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
14ca0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
14cb0 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
14cc0 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
14cd0 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
14ce0 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
14cf0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
14d00 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
14d10 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
14d20 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
14d30 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
14d40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14d50 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
14d60 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
14d70 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
14d80 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
14d90 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
14da0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
14db0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
14dc0 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
14dd0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14de0 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
14df0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14e00 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
14e10 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
14e20 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
14e30 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
14e40 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
14e50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
14e60 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
14e70 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
14e80 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14e90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14ea0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
14eb0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
14ec0 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
14ed0 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
14ee0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
14ef0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
14f00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14f10 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
14f20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
14f30 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
14f40 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
14f50 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
14f60 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
14f70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f80 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
14f90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14fa0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14fb0 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
14fc0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14fd0 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
14fe0 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
14ff0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
15000 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
15010 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
15020 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
15030 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
15040 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
15050 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
15060 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15070 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
15080 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15090 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
150a0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
150b0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
150c0 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
150d0 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
150e0 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
150f0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
15100 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
15110 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
15120 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
15130 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
15140 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15150 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
15160 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
15170 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
15180 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15190 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
151a0 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
151b0 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
151c0 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
151d0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
151e0 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
151f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15200 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
15210 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
15220 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
15230 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
15240 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
15250 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
15260 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15270 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15280 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15290 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
152a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
152b0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
152c0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
152d0 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
152e0 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
152f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
15300 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68   Windows.** with
15310 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
15320 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
15330 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15340 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54  efined..** SQLIT
15350 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
15360 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
15370 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
15380 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
15390 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
153a0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
153b0 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
153c0 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  heap..** </dl>.*
153d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
153e0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
153f0 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
15400 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15410 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
15420 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
15430 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15440 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
15450 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
15460 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
15470 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15480 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
15490 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
154a0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
154b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
154c0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
154d0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
154e0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
154f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15500 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
15510 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
15520 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
15530 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15540 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
15550 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
15560 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
15570 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15580 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
15590 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
155a0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
155b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
155c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
155d0 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
155e0 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
155f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15600 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
15610 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
15620 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15630 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15640 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
15650 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
15660 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
15670 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
15680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
15690 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
156a0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
156b0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
156c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
156d0 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
156e0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
156f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15700 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
15710 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
15720 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15730 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
15740 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
15750 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15760 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
15770 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
15780 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15790 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
157a0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
157b0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
157c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
157d0 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
157e0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
157f0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15810 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
15820 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
15830 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15840 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15860 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15870 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
15880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15890 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
158a0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
158b0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
158c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
158d0 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
158e0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
158f0 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
15900 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15910 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15920 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
15930 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
15940 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
15950 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
15960 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15970 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15980 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15990 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
159a0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
159b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
159c0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
159d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
159e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
159f0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15a00 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15a10 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
15a20 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
15a30 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
15a40 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
15a50 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
15a60 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15a70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15a80 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15a90 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
15aa0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
15ab0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
15ac0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
15ad0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15ae0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
15af0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15b00 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
15b10 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15b20 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
15b30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
15b40 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
15b50 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
15b60 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15b70 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15b80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15b90 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
15ba0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
15bb0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15bc0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15bd0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15be0 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
15bf0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15c00 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15c10 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
15c20 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15c30 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
15c40 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
15c50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15c60 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15c70 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15c80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15c90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15ca0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
15cb0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
15cc0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
15cd0 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
15ce0 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
15cf0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15d00 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
15d10 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15d20 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
15d30 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
15d40 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
15d50 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
15d60 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15d70 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15d80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15d90 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
15da0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15db0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
15dc0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15dd0 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
15de0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
15df0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15e00 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
15e10 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
15e20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15e30 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
15e40 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
15e50 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
15e60 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15e70 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15e80 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15e90 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
15ea0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15eb0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
15ec0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
15ed0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
15ee0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15ef0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15f00 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
15f10 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
15f20 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
15f30 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
15f40 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
15f50 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
15f60 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15f70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15f80 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15f90 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
15fa0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
15fb0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
15fc0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
15fd0 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
15fe0 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
15ff0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
16000 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
16010 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
16020 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
16030 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
16040 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16050 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
16060 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
16070 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
16080 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
16090 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
160a0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
160b0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
160c0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
160d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
160e0 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
160f0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
16100 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
16110 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
16120 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16130 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
16140 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
16150 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
16160 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
16170 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
16180 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
16190 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
161a0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
161b0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
161c0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
161d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
161e0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
161f0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
16200 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16210 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16220 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
16230 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
16240 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
16250 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
16260 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
16270 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
16280 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16290 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
162a0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
162b0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
162c0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
162d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
162e0 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
162f0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
16300 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16310 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
16320 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
16330 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16340 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
16350 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
16360 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16370 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
16380 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16390 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
163a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
163b0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
163c0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
163d0 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
163e0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
163f0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
16400 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16410 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16420 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16430 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16440 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16450 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
16460 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
16470 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
16480 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
16490 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
164a0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
164b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
164c0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
164d0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
164e0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
164f0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16500 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16510 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
16520 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
16530 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
16540 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16550 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16560 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16570 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16580 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
16590 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
165a0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
165b0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
165c0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
165d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
165e0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
165f0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
16600 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
16610 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
16620 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
16630 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
16640 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
16650 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16660 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
16670 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
16680 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
16690 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
166a0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
166b0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
166c0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
166d0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
166e0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
166f0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
16700 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
16710 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
16720 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
16730 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
16740 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
16750 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
16760 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
16770 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
16780 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16790 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
167a0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
167b0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
167c0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
167d0 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
167e0 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
167f0 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
16800 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
16810 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
16820 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
16830 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16840 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
16850 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
16860 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
16870 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
16880 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
16890 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
168a0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
168b0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
168c0 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
168d0 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
168e0 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
168f0 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
16900 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
16910 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
16920 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
16930 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
16940 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
16950 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
16960 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
16970 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
16980 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
16990 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
169a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
169b0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
169c0 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
169d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
169e0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
169f0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
16a00 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16a10 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
16a20 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
16a30 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
16a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16a50 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
16a60 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
16a70 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
16a80 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
16a90 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
16aa0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
16ab0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
16ac0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
16ad0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
16ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16af0 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
16b00 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16b10 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
16b20 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
16b30 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
16b40 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
16b50 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
16b60 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
16b70 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
16b80 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
16b90 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
16ba0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
16bb0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
16bc0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
16bd0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16be0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
16bf0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
16c00 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
16c10 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
16c20 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
16c30 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
16c40 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
16c50 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
16c60 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
16c70 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
16c80 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
16c90 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
16ca0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
16cb0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
16cc0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
16cd0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
16ce0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
16cf0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
16d00 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
16d10 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
16d20 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
16d30 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
16d40 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
16d50 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
16d60 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
16d70 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
16d80 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
16d90 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
16da0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
16db0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
16dc0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
16dd0 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
16de0 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
16df0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
16e00 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
16e10 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
16e20 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
16e30 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
16e40 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
16e50 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
16e60 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
16e70 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
16e80 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
16e90 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
16ea0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
16eb0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
16ec0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
16ed0 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
16ee0 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
16ef0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
16f00 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
16f10 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
16f20 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
16f30 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
16f40 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
16f50 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
16f60 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
16f70 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
16f80 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
16f90 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
16fa0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
16fb0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
16fc0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
16fd0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
16fe0 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
16ff0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
17000 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
17010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17020 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
17030 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17040 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
17050 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
17060 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
17070 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
17080 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
17090 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
170a0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
170b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
170c0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
170d0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
170e0 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
170f0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
17100 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
17110 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
17120 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
17130 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
17140 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17150 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
17160 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17170 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
17180 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
17190 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
171a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
171b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
171c0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
171d0 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
171e0 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
171f0 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
17200 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
17210 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
17220 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
17230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17240 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
17250 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
17260 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
17270 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
17280 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
17290 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
172a0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
172b0 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
172c0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
172d0 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
172e0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
172f0 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
17300 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
17310 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
17320 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
17330 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17340 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
17350 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
17360 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
17370 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
17380 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
17390 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
173a0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
173b0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
173c0 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
173d0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
173e0 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
173f0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17400 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
17410 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
17420 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
17430 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17440 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
17450 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
17460 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
17470 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
17480 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
17490 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
174a0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
174b0 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
174c0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
174d0 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
174e0 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
174f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
17500 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
17510 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
17520 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
17530 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17540 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
17550 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
17560 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
17570 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
17580 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
17590 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
175a0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
175b0 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
175c0 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
175d0 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
175e0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
175f0 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
17600 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17610 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
17620 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
17630 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17640 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
17650 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17660 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
17670 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
17680 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
17690 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
176a0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
176b0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
176c0 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
176d0 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
176e0 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
176f0 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
17700 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
17710 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
17720 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
17730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17740 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
17750 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
17760 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
17770 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
17780 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
177a0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
177b0 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
177c0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
177d0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
177e0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
177f0 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
17800 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
17810 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
17820 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
17830 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17840 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17850 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
17860 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
17870 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17880 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17890 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
178a0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
178b0 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
178c0 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
178d0 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
178e0 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
178f0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
17900 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
17910 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
17920 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17930 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17940 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17950 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17960 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
17970 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17980 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
17990 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
179a0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
179b0 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
179c0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
179d0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
179e0 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
179f0 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
17a00 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
17a10 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
17a20 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17a30 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17a40 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17a50 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17a60 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17a70 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17a80 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17a90 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17aa0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17ab0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17ac0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17ad0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17ae0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
17af0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17b00 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17b10 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17b20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17b30 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17b40 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17b50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
17b60 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17b70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17b80 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
17b90 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17ba0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17bb0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17bc0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
17bd0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17be0 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
17bf0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
17c00 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
17c10 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
17c20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
17c30 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
17c40 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
17c50 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
17c60 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
17c70 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
17c80 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
17c90 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17ca0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
17cb0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
17cc0 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
17cd0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
17ce0 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
17cf0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17d00 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
17d10 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
17d20 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
17d30 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
17d40 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
17d50 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
17d60 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
17d70 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
17d80 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
17d90 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
17da0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
17db0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17dc0 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
17dd0 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
17de0 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
17df0 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
17e00 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
17e10 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
17e20 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
17e30 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17e40 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
17e50 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
17e60 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
17e70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
17e80 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
17e90 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
17ea0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
17eb0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
17ec0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
17ed0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
17ee0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
17ef0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
17f00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
17f10 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
17f20 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
17f30 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
17f40 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
17f50 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
17f60 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17f70 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17f80 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17f90 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17fa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17fb0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
17fc0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17fd0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17fe0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17ff0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
18000 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18010 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18020 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18030 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
18040 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
18050 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
18060 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
18070 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
18080 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
18090 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
180a0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
180b0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
180c0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
180d0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
180e0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
180f0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
18100 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
18110 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
18120 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
18130 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
18140 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
18150 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
18160 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
18170 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
18180 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
18190 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
181a0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
181b0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
181c0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
181d0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
181e0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
181f0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
18200 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
18210 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18220 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
18230 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
18240 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
18250 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
18260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
18270 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
18280 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
18290 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
182a0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
182b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
182c0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
182d0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
182e0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
182f0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
18300 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
18310 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
18320 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
18330 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
18340 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
18350 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
18360 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
18370 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
18380 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
18390 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
183a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
183b0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
183c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
183d0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
183e0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
183f0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
18400 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
18410 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
18420 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
18430 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
18440 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
18450 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
18460 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
18470 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
18480 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18490 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
184a0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
184b0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
184c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
184d0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
184e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
184f0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
18500 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
18510 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
18520 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
18530 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18540 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
18550 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
18560 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
18570 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
18580 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
18590 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
185a0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
185b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
185c0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
185d0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
185e0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
185f0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18600 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
18610 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
18620 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
18630 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
18640 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18650 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
18660 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
18670 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
18680 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
18690 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
186a0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
186b0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
186c0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
186d0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
186e0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
186f0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18700 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18710 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
18720 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
18730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18740 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
18750 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
18760 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
18770 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
18780 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
18790 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
187a0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
187b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
187c0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
187d0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
187e0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
187f0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
18800 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
18810 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
18820 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
18830 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
18840 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
18850 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
18860 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
18870 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
18880 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18890 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
188a0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
188b0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
188c0 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
188d0 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
188e0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
188f0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18900 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
18910 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
18920 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
18930 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18940 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
18950 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
18960 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
18970 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
18980 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
18990 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
189a0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
189b0 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
189c0 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
189d0 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
189e0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
189f0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
18a00 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
18a10 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
18a20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
18a30 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
18a40 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
18a50 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
18a60 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
18a70 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
18a80 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
18a90 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
18aa0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
18ab0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
18ac0 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
18ad0 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
18ae0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
18af0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
18b00 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
18b10 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18b20 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
18b30 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
18b40 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
18b50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18b60 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
18b70 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
18b80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
18b90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
18ba0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
18bb0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
18bc0 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
18bd0 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
18be0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
18bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
18c00 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
18c10 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
18c20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
18c30 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
18c40 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
18c50 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18c60 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
18c70 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
18c80 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
18c90 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
18ca0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18cb0 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
18cc0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
18cd0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
18ce0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
18cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18d00 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
18d10 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
18d20 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
18d30 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
18d40 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
18d50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
18d60 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
18d70 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
18d80 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
18d90 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
18da0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
18db0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18dc0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
18dd0 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18de0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18df0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
18e00 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
18e10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
18e30 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
18e40 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
18e50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
18e60 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
18e70 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
18e80 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
18e90 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
18ea0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
18eb0 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
18ec0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18ed0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
18ee0 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
18ef0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
18f00 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
18f10 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
18f20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
18f30 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
18f40 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
18f50 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
18f60 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
18f70 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
18f80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18f90 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
18fa0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
18fb0 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
18fc0 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
18fd0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
18fe0 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
18ff0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
19000 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
19010 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19020 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
19030 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
19040 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
19050 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
19060 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
19070 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
19080 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
19090 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
190a0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
190b0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
190c0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
190d0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
190e0 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
190f0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
19100 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
19110 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
19120 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
19130 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
19140 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
19150 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
19160 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
19170 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
19180 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19190 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
191a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
191b0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
191c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
191d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
191e0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
191f0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
19200 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
19210 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
19220 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
19230 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
19240 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
19250 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
19260 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
19270 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
19280 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
19290 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
192a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
192b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
192c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
192d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
192e0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
192f0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
19300 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
19310 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
19320 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
19330 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
19340 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
19350 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
19360 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
19370 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
19380 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
19390 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
193a0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
193b0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
193c0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
193d0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
193e0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
193f0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
19400 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
19410 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
19420 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
19430 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
19440 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
19450 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
19460 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
19470 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
19480 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
19490 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
194a0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
194b0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
194c0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
194d0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
194e0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
194f0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
19500 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
19510 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
19520 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
19530 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
19540 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
19550 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
19560 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
19570 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19580 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
19590 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
195a0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
195b0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
195c0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
195d0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
195e0 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
195f0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
19600 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
19610 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
19620 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
19630 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
19640 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
19650 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
19660 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
19670 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
19680 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
19690 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
196a0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
196b0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
196c0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
196d0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
196e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
196f0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
19700 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
19710 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
19720 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
19730 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
19740 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
19750 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19760 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
19770 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
19780 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
19790 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
197a0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
197b0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
197c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
197d0 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
197e0 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
197f0 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
19800 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
19810 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
19820 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
19830 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
19840 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
19850 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
19860 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
19870 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
19880 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
19890 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
198a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
198b0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
198c0 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
198d0 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
198e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
198f0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
19900 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19910 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19920 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
19930 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
19940 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19950 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19970 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
19980 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19990 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
199a0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
199b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
199c0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
199d0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
199e0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
199f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19a00 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
19a10 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
19a20 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
19a30 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
19a40 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
19a50 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
19a60 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
19a70 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
19a80 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
19a90 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
19aa0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
19ab0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
19ac0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
19ad0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
19ae0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19af0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
19b00 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
19b10 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
19b20 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19b30 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
19b40 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
19b50 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
19b60 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
19b70 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
19b80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
19b90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
19ba0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
19bb0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
19bc0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
19bd0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
19be0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
19bf0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
19c00 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
19c10 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
19c20 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
19c30 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
19c40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19c50 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
19c60 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
19c70 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
19c80 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
19c90 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
19ca0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19cb0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
19cc0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
19cd0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
19ce0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19cf0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
19d00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
19d10 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
19d20 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t].*/.SQLITE_API
19d30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
19d40 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
19d50 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
19d60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
19d70 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
19d80 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
19d90 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
19da0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
19db0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
19dc0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
19dd0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
19de0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
19df0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
19e00 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
19e10 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
19e20 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
19e30 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
19e40 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
19e50 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
19e60 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
19e70 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
19e80 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
19e90 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
19ea0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
19eb0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
19ec0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
19ed0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
19ee0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
19ef0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
19f00 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
19f10 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
19f20 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
19f30 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
19f40 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
19f50 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
19f60 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
19f70 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
19f80 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
19f90 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
19fa0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
19fb0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
19fc0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
19fd0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
19fe0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
19ff0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a000 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1a010 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1a020 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1a030 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1a040 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1a050 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1a060 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1a070 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1a080 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1a090 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1a0a0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1a0b0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1a0c0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1a0d0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1a0e0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1a0f0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1a100 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1a110 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1a120 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a130 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1a140 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1a150 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1a160 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1a170 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1a180 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1a190 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1a1a0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1a1b0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1a1c0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1a1d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1a1e0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1a1f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1a200 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a210 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1a220 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1a230 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1a240 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1a250 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1a260 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1a270 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1a280 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1a290 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1a2a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a2b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1a2c0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1a2d0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1a2e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a2f0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1a300 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1a310 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1a320 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1a330 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1a340 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1a350 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1a360 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1a370 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1a380 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1a390 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1a3a0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1a3b0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1a3c0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1a3d0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1a3e0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1a3f0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1a400 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1a410 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1a420 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1a430 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a440 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a450 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1a460 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a470 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1a480 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1a490 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1a4a0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1a4b0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a4c0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1a4d0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a4e0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1a4f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a500 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1a510 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a520 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1a530 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1a540 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1a550 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1a560 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1a570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a580 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1a590 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1a5a0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1a5b0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1a5c0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1a5d0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1a5e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a5f0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1a600 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1a610 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1a620 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1a630 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1a640 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1a650 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1a660 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1a670 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1a680 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1a690 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1a6a0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1a6b0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1a6c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1a6d0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1a6e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1a6f0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1a700 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1a710 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1a720 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1a730 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1a740 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1a750 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1a760 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a770 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1a780 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1a790 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1a7a0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1a7b0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1a7c0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1a7d0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1a7e0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1a7f0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1a800 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1a810 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1a820 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1a830 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1a840 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1a850 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1a860 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1a870 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1a880 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1a890 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1a8a0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1a8b0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1a8c0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1a8d0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1a8e0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1a8f0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1a900 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1a910 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1a920 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1a930 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1a940 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1a950 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1a960 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1a970 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1a980 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1a990 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1a9a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1a9b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1a9c0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1a9d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1a9e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a9f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1aa00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1aa10 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1aa20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1aa30 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1aa40 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1aa50 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1aa60 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1aa70 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1aa80 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1aa90 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1aaa0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1aab0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1aac0 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1aad0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1aae0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1aaf0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1ab00 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1ab10 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1ab20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1ab30 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1ab40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1ab50 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1ab60 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1ab70 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1ab80 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1ab90 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1aba0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1abb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1abc0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1abd0 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1abe0 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1abf0 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1ac00 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1ac10 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
1ac20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1ac30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1ac40 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1ac50 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1ac60 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1ac70 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1ac80 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1ac90 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1aca0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1acb0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1acc0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1acd0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1ace0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1acf0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1ad00 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1ad10 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1ad20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1ad30 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1ad40 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1ad50 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1ad60 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1ad70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1ad80 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1ad90 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1ada0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1adb0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1adc0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1add0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1ade0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1adf0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1ae00 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1ae10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1ae20 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1ae30 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1ae40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1ae50 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1ae60 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1ae70 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1ae80 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1ae90 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1aea0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1aeb0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1aec0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1aed0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1aee0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1aef0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1af00 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1af10 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1af20 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1af30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1af40 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1af50 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1af60 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1af70 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1af80 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1af90 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1afa0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1afb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1afc0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1afd0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1afe0 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1aff0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1b000 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1b010 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1b020 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b030 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1b040 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1b050 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1b060 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1b070 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1b080 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1b090 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1b0a0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1b0b0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1b0c0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1b0d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1b0e0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1b0f0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1b100 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1b110 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1b120 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1b130 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1b140 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1b150 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1b160 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1b170 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1b180 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1b190 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1b1a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1b1b0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1b1c0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1b1d0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1b1e0 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1b1f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b200 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1b210 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1b220 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1b230 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1b240 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1b250 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1b260 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1b270 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1b280 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1b290 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1b2a0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1b2b0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1b2c0 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1b2d0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1b2e0 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1b2f0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1b300 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1b310 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1b320 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1b330 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1b340 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1b350 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1b360 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1b370 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1b380 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1b390 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1b3a0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1b3b0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1b3c0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1b3d0 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1b3e0 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1b3f0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1b400 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1b410 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1b420 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1b430 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1b440 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1b450 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1b460 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b470 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b480 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1b490 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1b4a0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1b4b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b4c0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1b4d0 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1b4e0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1b4f0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b500 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b510 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1b520 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1b530 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1b540 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1b550 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1b560 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1b570 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1b580 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1b590 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1b5a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b5b0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1b5c0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1b5d0 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1b5e0 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1b5f0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1b600 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1b610 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1b620 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1b630 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b640 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1b650 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1b660 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1b670 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1b680 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b690 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1b6a0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1b6b0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1b6c0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1b6d0 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1b6e0 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1b6f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1b700 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1b710 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1b720 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1b730 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1b740 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b750 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1b760 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1b770 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1b780 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1b790 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1b7a0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1b7b0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1b7c0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1b7d0 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1b7e0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1b7f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1b800 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1b810 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1b820 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1b830 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1b840 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1b850 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1b860 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1b870 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1b880 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1b890 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1b8a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1b8b0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1b8c0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1b8d0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1b8e0 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1b8f0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1b900 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1b910 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b920 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1b930 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1b940 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1b950 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1b960 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1b970 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1b980 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1b990 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1b9a0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1b9b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b9c0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1b9d0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1b9e0 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1b9f0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1ba00 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1ba10 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1ba20 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1ba30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1ba40 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1ba50 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1ba60 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1ba70 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1ba80 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1ba90 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1baa0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1bab0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1bac0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1bad0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1bae0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1baf0 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1bb00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
1bb10 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1bb20 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1bb30 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1bb40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1bb50 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1bb60 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
1bb70 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1bb80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1bb90 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1bba0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1bbb0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1bbc0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1bbd0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1bbe0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1bbf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bc00 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1bc10 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1bc20 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1bc30 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1bc40 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1bc50 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1bc60 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1bc70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1bc80 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1bc90 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1bca0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1bcb0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1bcc0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1bcd0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1bce0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1bcf0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1bd00 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1bd10 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1bd20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1bd30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1bd40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1bd50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1bd60 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1bd70 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1bd80 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1bd90 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1bda0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1bdb0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1bdc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1bdd0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1bde0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1bdf0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1be00 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1be10 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1be20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1be30 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1be40 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1be50 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1be60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1be70 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1be80 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1be90 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1bea0 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1beb0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1bec0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1bed0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1bee0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1bef0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1bf00 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1bf10 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1bf20 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1bf30 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1bf40 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1bf50 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1bf60 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1bf70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1bf80 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1bf90 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1bfa0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1bfb0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1bfc0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1bfd0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1bfe0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1bff0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1c000 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1c010 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1c020 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1c030 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1c040 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1c050 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1c060 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1c070 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1c080 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1c090 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1c0a0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1c0b0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1c0c0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1c0d0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1c0e0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1c0f0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1c100 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1c110 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c120 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1c130 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1c140 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1c150 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1c160 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1c170 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1c180 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1c190 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1c1a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1c1b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c1c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c1d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c1e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1c1f0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1c200 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1c210 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1c220 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1c230 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1c240 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1c250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c260 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1c270 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1c280 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1c290 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1c2a0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1c2b0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1c2c0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1c2d0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1c2e0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1c2f0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1c300 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1c310 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1c320 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1c330 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1c340 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1c350 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1c360 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1c370 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1c380 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1c390 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1c3a0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1c3b0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1c3c0 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1c3d0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1c3e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1c3f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1c400 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1c410 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1c420 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1c430 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1c440 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1c450 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1c460 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1c470 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1c480 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1c490 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1c4a0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1c4b0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1c4c0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1c4d0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1c4e0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1c4f0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1c500 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c510 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1c520 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1c530 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1c540 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1c550 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1c560 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1c570 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1c580 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1c590 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1c5a0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1c5b0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1c5c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c5d0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1c5e0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1c5f0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1c600 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1c610 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1c620 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1c630 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1c640 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1c650 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1c660 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1c670 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c680 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1c690 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1c6a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1c6b0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1c6c0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1c6d0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1c6e0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1c6f0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1c700 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1c710 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1c720 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1c730 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1c740 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1c750 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1c760 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1c770 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1c780 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1c790 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1c7a0 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1c7b0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1c7c0 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1c7d0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1c7e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1c7f0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1c800 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1c810 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1c820 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1c830 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1c840 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1c850 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1c860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1c870 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1c880 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1c890 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1c8a0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1c8b0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1c8c0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1c8d0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1c8e0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1c8f0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1c900 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1c910 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1c920 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1c930 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1c940 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1c950 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1c960 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1c970 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1c980 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1c990 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1c9a0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1c9b0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1c9c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c9d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1c9e0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1c9f0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1ca00 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1ca10 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1ca20 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1ca30 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1ca40 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1ca50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1ca60 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1ca70 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1ca80 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1ca90 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1caa0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1cab0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1cac0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1cad0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1cae0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1caf0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1cb00 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1cb10 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1cb20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1cb30 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1cb40 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1cb50 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1cb60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1cb70 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1cb80 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1cb90 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1cba0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1cbb0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1cbc0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1cbd0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1cbe0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1cbf0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1cc00 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1cc10 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1cc20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1cc30 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1cc40 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1cc50 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1cc60 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1cc70 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1cc80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cc90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1cca0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1ccb0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1ccc0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1ccd0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1cce0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1ccf0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1cd00 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1cd10 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1cd20 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1cd30 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1cd40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1cd50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1cd60 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1cd70 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1cd80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1cd90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1cda0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1cdb0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1cdc0 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
1cdd0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72   void *sqlite3_r
1cde0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1cdf0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1ce00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1ce10 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
1ce20 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53  lite3_uint64);.S
1ce30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1ce40 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1ce50 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
1ce60 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71  qlite3_uint64 sq
1ce70 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
1ce80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1ce90 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1cea0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1ceb0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1cec0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1ced0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1cee0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1cef0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1cf00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1cf10 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1cf20 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1cf30 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1cf40 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1cf50 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1cf60 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1cf70 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1cf80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1cf90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1cfa0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1cfb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1cfc0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1cfd0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1cfe0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1cff0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1d000 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1d010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d020 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1d030 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1d040 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1d050 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1d060 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1d070 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1d080 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1d090 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1d0a0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1d0b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d0c0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1d0d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d0e0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1d0f0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1d100 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1d110 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1d120 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1d130 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d140 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1d150 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1d160 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1d170 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1d180 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1d190 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1d1a0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1d1b0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1d1c0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1d1d0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1d1e0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1d1f0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1d200 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1d210 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1d220 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1d230 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d240 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1d250 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1d260 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1d270 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d280 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1d290 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1d2a0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1d2b0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1d2c0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1d2d0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1d2e0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1d2f0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1d300 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1d310 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d320 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1d330 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1d340 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1d350 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1d360 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1d370 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1d380 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1d390 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1d3a0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1d3b0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1d3c0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1d3d0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1d3e0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1d3f0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1d400 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1d410 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1d420 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1d430 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1d440 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1d450 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1d460 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1d470 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1d480 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1d490 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1d4a0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1d4b0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1d4c0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1d4d0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1d4e0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1d4f0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1d500 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1d510 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1d520 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 4e 20  fer P..** ^If N 
1d530 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
1d540 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62 65 20  , then P can be 
1d550 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1d560 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1d570 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1d580 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1d590 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1d5a0 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1d5b0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1d5c0 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65 20 50   one, then the P
1d5d0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
1d5e0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 0a 2a  ing randomness.*
1d5f0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
1d600 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1d610 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
1d620 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1d630 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1d640 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1d650 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1d660 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1d670 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65 6e 0a   1 or more then.
1d680 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  ** the pseudo-ra
1d690 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1d6a0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1d6b0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1d6c0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1d6d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1d6e0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1d6f0 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  hod..*/.SQLITE_A
1d700 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1d710 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1d720 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1d730 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1d740 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1d750 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1d760 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1d770 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
1d780 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
1d790 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
1d7a0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1d7b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d7c0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
1d7d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1d7e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
1d7f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1d800 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
1d810 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1d820 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
1d830 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
1d840 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1d850 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
1d860 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1d870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d880 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
1d890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d8a0 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
1d8b0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
1d8c0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
1d8d0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
1d8e0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
1d8f0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
1d900 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
1d910 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
1d920 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d930 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
1d940 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
1d950 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
1d960 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
1d970 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
1d980 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
1d990 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
1d9a0 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
1d9b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1d9c0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
1d9d0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
1d9e0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
1d9f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1da00 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
1da10 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
1da20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
1da30 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
1da40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1da50 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
1da60 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
1da70 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
1da80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1da90 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
1daa0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1dab0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
1dac0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
1dad0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
1dae0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
1daf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1db00 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1db10 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1db20 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
1db30 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1db40 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1db50 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
1db60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1db70 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1db80 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1db90 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
1dba0 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
1dbb0 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
1dbc0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1dbd0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
1dbe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dbf0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1dc00 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1dc10 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
1dc20 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1dc30 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1dc40 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
1dc50 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
1dc60 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
1dc70 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
1dc80 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1dc90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1dca0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1dcb0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
1dcc0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1dcd0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
1dce0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
1dcf0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
1dd00 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
1dd10 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1dd20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
1dd30 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1dd40 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1dd50 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
1dd60 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
1dd70 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1dd80 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
1dd90 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
1dda0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
1ddb0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
1ddc0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1ddd0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1dde0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
1ddf0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
1de00 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
1de10 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1de20 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1de30 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1de40 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
1de50 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1de60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
1de70 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
1de80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1de90 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
1dea0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
1deb0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
1dec0 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
1ded0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
1dee0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
1def0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
1df00 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
1df10 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
1df20 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
1df30 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
1df40 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
1df50 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
1df60 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
1df70 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
1df80 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
1df90 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
1dfa0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1dfb0 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
1dfc0 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
1dfd0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
1dfe0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1dff0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
1e000 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1e010 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
1e020 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
1e030 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
1e040 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
1e050 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
1e060 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
1e070 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
1e080 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
1e090 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1e0a0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
1e0b0 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
1e0c0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
1e0d0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
1e0e0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
1e0f0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
1e100 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
1e110 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
1e120 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
1e130 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
1e140 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
1e150 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
1e160 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
1e170 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
1e180 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
1e190 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
1e1a0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
1e1b0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
1e1c0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
1e1d0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
1e1e0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
1e1f0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
1e200 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1e210 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
1e220 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
1e230 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
1e240 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
1e250 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
1e260 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
1e270 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
1e280 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
1e290 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1e2a0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1e2b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e2c0 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1e2d0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1e2e0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1e2f0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1e300 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1e310 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1e320 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1e330 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1e340 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1e350 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1e360 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1e370 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1e380 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1e390 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1e3a0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1e3b0 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1e3c0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1e3d0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1e3e0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1e3f0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1e400 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1e410 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1e420 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1e430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e440 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1e450 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1e460 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1e470 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1e480 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1e490 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1e4a0 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1e4b0 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1e4c0 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1e4d0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1e4e0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1e4f0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1e500 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1e510 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1e520 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1e530 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1e540 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1e550 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1e560 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1e570 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1e580 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1e590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e5a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e5b0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1e5c0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1e5d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e5e0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1e5f0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1e600 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1e610 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1e620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e630 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1e640 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1e650 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1e660 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1e670 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1e680 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1e690 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1e6a0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1e6b0 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1e6c0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1e6d0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1e6e0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1e6f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1e700 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1e710 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1e720 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1e730 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1e740 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e750 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1e760 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1e770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1e780 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1e790 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1e7a0 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1e7b0 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1e7c0 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1e7d0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1e7e0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1e7f0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1e800 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1e810 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1e820 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1e830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e840 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1e850 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1e860 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1e870 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  nge..*/.SQLITE_A
1e880 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
1e890 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1e8a0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1e8b0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1e8c0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1e8d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1e8e0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1e8f0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1e900 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1e910 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1e920 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1e930 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1e940 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1e950 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1e960 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1e970 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1e980 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1e990 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1e9a0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1e9b0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1e9c0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1e9d0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1e9e0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1e9f0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1ea00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1ea10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1ea20 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1ea30 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1ea40 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1ea50 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1ea60 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1ea70 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1ea80 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
1ea90 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
1eaa0 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
1eab0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1eac0 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1ead0 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1eae0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1eaf0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1eb00 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1eb10 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1eb20 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1eb30 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1eb40 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1eb50 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1eb60 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1eb70 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1eb80 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1eb90 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1eba0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1ebb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ebc0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1ebd0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1ebe0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1ebf0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1ec00 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1ec10 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1ec20 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1ec30 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1ec40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ec50 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1ec60 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1ec70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1ec80 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1ec90 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1eca0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1ecb0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1ecc0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1ecd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ece0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1ecf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1ed00 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1ed10 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1ed20 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1ed30 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1ed40 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1ed50 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1ed60 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1ed70 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1ed80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1ed90 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1eda0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1edb0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1edc0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1edd0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1ede0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1edf0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1ee00 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1ee10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ee20 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1ee30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1ee40 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1ee50 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1ee60 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1ee70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1ee80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ee90 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1eea0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1eeb0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1eec0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1eed0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1eee0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1eef0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1ef00 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1ef10 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1ef20 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1ef30 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1ef40 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1ef50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ef60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1ef70 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1ef80 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1ef90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1efa0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1efb0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1efc0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1efd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1efe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1eff0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1f000 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1f010 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f020 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f040 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1f050 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1f060 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f070 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f080 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f090 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1f0a0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1f0b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f0c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f0d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f0e0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1f0f0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1f100 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f110 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f120 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f130 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1f140 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1f150 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f160 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f170 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f180 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1f190 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f1a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f1b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f1c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1f1d0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1f1e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f1f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f200 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f210 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1f220 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1f230 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f240 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f250 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f260 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1f270 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1f280 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f290 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f2a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f2b0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1f2c0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1f2d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f2e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f2f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f300 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1f310 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1f320 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f330 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f340 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f350 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1f360 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1f370 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f380 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f390 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f3a0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1f3b0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1f3c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f3d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f3e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f3f0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1f400 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1f410 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f420 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f440 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1f450 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1f460 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f470 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f490 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1f4a0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1f4b0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f4c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f4d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1f4e0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1f4f0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1f500 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f510 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f520 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1f530 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1f540 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1f550 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1f560 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1f570 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1f580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f590 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1f5a0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1f5b0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1f5c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1f5d0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1f5e0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1f5f0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1f600 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f610 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1f620 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1f630 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1f640 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f650 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f660 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1f670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1f680 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f690 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1f6a0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1f6b0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1f6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1f6d0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1f6e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f6f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f700 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1f710 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1f720 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1f730 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1f740 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f750 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1f760 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1f770 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1f780 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f790 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f7a0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1f7b0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1f7c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f7d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f7e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f7f0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1f800 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1f810 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f820 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f830 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f840 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1f850 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1f860 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f870 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1f880 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f890 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1f8a0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1f8b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1f8c0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1f8d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f8e0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1f8f0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1f900 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1f910 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1f920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f930 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1f940 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1f950 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1f960 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1f970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f980 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1f990 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1f9a0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
1f9b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
1f9c0 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
1f9d0 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
1f9e0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1f9f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
1fa00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1fa10 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1fa20 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1fa30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1fa40 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1fa50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1fa60 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1fa70 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1fa80 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1fa90 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1faa0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1fab0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1fac0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1fad0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1fae0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1faf0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1fb00 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1fb10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1fb20 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1fb30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1fb40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1fb50 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1fb60 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1fb70 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1fb80 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1fb90 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1fba0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1fbb0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1fbc0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1fbd0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1fbe0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1fbf0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1fc00 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1fc10 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1fc20 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1fc30 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1fc40 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1fc50 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1fc60 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1fc70 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1fc80 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
1fc90 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
1fca0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
1fcb0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
1fcc0 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
1fcd0 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
1fce0 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
1fcf0 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
1fd00 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
1fd10 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
1fd20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1fd30 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1fd40 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1fd50 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1fd60 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1fd70 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1fd80 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1fd90 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1fda0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1fdb0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1fdc0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1fdd0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1fde0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1fdf0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1fe00 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1fe10 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1fe20 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1fe30 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1fe40 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1fe50 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1fe60 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1fe70 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1fe80 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1fe90 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1fea0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1feb0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1fec0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1fed0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1fee0 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1fef0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1ff00 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1ff10 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1ff20 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1ff30 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1ff40 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1ff50 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1ff60 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1ff70 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1ff80 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1ff90 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1ffa0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1ffb0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
1ffc0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1ffd0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1ffe0 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1fff0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
20000 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
20010 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
20020 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
20030 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
20040 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
20050 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
20060 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
20070 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
20080 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
20090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
200a0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
200b0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
200c0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
200d0 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
200e0 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
200f0 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
20100 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
20110 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
20120 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
20130 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
20140 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
20150 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
20160 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
20170 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
20180 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
20190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
201a0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
201b0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
201c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
201d0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
201e0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
201f0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
20200 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
20210 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
20220 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
20230 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20240 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
20250 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
20260 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
20270 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
20280 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
20290 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
202a0 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
202b0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
202c0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
202d0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
202e0 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
202f0 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
20300 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
20310 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
20320 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
20330 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
20340 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
20350 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
20360 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
20370 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
20380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20390 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
203a0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
203b0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
203c0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
203d0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
203e0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
203f0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
20400 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
20410 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20420 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
20430 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
20440 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
20450 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
20460 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
20470 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20480 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
20490 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
204a0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
204b0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
204c0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
204d0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
204e0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
204f0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
20500 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
20510 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20520 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
20530 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
20540 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
20550 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
20560 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
20570 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
20580 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
20590 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
205a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
205b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
205c0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
205d0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
205e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
205f0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
20600 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
20610 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
20620 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
20630 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
20640 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
20650 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
20660 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
20670 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
20680 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
20690 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
206a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
206b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
206c0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
206d0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
206e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
206f0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
20700 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
20710 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
20720 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
20730 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
20740 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
20750 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20760 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
20770 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
20780 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
20790 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
207a0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
207b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
207c0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
207d0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
207e0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
207f0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
20800 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
20810 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
20820 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
20830 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
20840 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
20850 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
20860 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
20870 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
20880 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
20890 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
208a0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
208b0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
208c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
208d0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
208e0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
208f0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
20900 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
20910 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
20920 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
20930 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
20940 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
20950 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
20960 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
20970 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
20980 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
20990 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
209a0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
209b0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
209c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
209d0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
209e0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
209f0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
20a00 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
20a10 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
20a20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
20a30 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
20a40 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
20a50 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
20a60 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
20a70 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
20a80 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
20a90 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
20aa0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
20ab0 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
20ac0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
20ad0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
20ae0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
20af0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
20b00 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
20b10 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
20b20 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
20b30 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
20b40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
20b50 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
20b60 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
20b70 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
20b80 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
20b90 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
20ba0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
20bb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
20bc0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
20bd0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
20be0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
20bf0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
20c00 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
20c10 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
20c20 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
20c30 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
20c40 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
20c50 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
20c60 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
20c70 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
20c80 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
20c90 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
20ca0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
20cb0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
20cc0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
20cd0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
20ce0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
20cf0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
20d00 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
20d10 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
20d20 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
20d30 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20d40 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
20d50 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
20d60 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
20d70 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20d80 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
20d90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20da0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20db0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
20dc0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
20dd0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
20de0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
20df0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
20e00 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20e10 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20e20 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20e30 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
20e40 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
20e50 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
20e60 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
20e70 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
20e80 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
20e90 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
20ea0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
20eb0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
20ec0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
20ed0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
20ee0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
20ef0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
20f00 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
20f10 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
20f20 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
20f30 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
20f40 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
20f50 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
20f60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20f70 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20f80 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
20f90 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
20fa0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
20fb0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
20fc0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
20fd0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
20fe0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
20ff0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
21000 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21010 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
21020 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
21030 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
21040 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21050 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21060 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
21070 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
21080 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
21090 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
210a0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
210b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
210c0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
210d0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
210e0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
210f0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
21100 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
21110 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
21120 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
21130 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21140 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
21150 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
21160 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
21170 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
21180 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
21190 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
211a0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
211b0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
211c0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
211d0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
211e0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
211f0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
21200 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21210 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
21220 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
21230 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
21240 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
21250 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
21260 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
21270 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
21280 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
21290 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
212a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
212b0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
212c0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
212d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
212e0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
212f0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
21300 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
21310 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
21320 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
21330 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
21340 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
21350 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
21360 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
21370 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
21380 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
21390 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
213a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
213b0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
213c0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
213d0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
213e0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
213f0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
21400 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21410 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21420 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
21430 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
21440 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
21450 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
21460 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21470 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
21480 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
21490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
214a0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
214b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
214c0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
214d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
214e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
214f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
21500 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
21510 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
21520 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
21530 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
21540 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
21550 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
21560 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
21570 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
21580 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
21590 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
215a0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
215b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
215c0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
215d0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
215e0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
215f0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
21600 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
21610 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
21620 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
21630 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
21640 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
21650 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
21660 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
21670 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
21680 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
21690 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
216a0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
216b0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
216c0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
216d0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
216e0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
216f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
21700 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
21710 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
21720 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
21730 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
21740 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
21750 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
21760 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
21770 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
21780 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
21790 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
217a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
217b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
217c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
217d0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
217e0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
217f0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
21800 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
21810 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
21820 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
21830 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
21840 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
21850 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
21860 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
21870 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
21880 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21890 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
218a0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
218b0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
218c0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
218d0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
218e0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
218f0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
21900 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21910 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
21920 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
21930 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
21940 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
21950 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
21960 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
21970 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
21980 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
21990 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
219a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
219b0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
219c0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
219d0 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
219e0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
219f0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
21a00 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
21a10 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
21a20 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
21a30 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
21a40 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
21a50 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
21a60 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
21a70 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
21a80 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21a90 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21aa0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
21ab0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
21ac0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
21ad0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
21ae0 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
21af0 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
21b00 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
21b10 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
21b20 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
21b30 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
21b40 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
21b50 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
21b60 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
21b70 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
21b80 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
21b90 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
21ba0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
21bb0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
21bc0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
21bd0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
21be0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
21bf0 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
21c00 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
21c10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21c20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
21c30 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
21c40 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
21c50 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
21c60 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
21c70 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
21c80 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21c90 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
21ca0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
21cb0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
21cc0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
21cd0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
21ce0 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
21cf0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
21d00 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
21d10 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
21d20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21d30 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
21d40 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73  .** ^(On windows
21d50 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
21d60 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
21d70 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
21d80 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
21d90 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
21da0 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  ").)^.**.** [[co
21db0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
21dc0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
21dd0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
21de0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
21df0 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
21e00 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
21e10 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
21e20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
21e30 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
21e40 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
21e50 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
21e60 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62  SQLite and its b
21e70 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20  uilt-in [VFSes] 
21e80 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
21e90 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
21ea0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
21eb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
21ec0 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
21ed0 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
21ee0 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
21ef0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
21f00 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
21f10 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
21f20 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
21f30 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
21f40 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
21f50 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
21f60 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
21f70 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
21f80 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
21f90 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
21fa0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
21fb0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
21fc0 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
21fd0 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
21fe0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
21ff0 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
22000 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
22010 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22020 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
22030 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
22040 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
22050 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
22060 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
22070 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
22080 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
22090 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
220a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
220b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
220c0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
220d0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
220e0 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
220f0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22100 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
22110 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
22120 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
22130 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
22140 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
22150 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
22160 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
22170 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
22180 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
22190 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
221a0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
221b0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
221c0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
221d0 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
221e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
221f0 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
22200 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
22210 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
22220 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
22230 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
22240 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
22250 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
22260 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
22270 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22280 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
22290 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
222a0 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
222b0 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
222c0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
222d0 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
222e0 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
222f0 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
22300 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
22310 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
22320 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
22330 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
22340 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
22350 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
22360 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
22370 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
22380 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
22390 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
223a0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
223b0 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
223c0 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
223d0 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
223e0 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
223f0 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
22400 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
22410 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
22420 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
22430 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
22440 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
22450 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
22460 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
22470 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
22480 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
22490 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
224a0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
224b0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
224c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
224d0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
224e0 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
224f0 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
22500 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
22510 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
22520 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
22530 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
22540 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
22550 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
22560 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
22570 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
22580 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22590 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
225a0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
225b0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
225c0 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
225d0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
225e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
225f0 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
22600 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
22610 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
22620 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
22630 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
22640 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
22650 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
22660 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
22670 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
22680 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
22690 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
226a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
226b0 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
226c0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
226d0 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
226e0 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62   <li> <b>psow</b
226f0 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72  >: ^The psow par
22700 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73  ameter indicates
22710 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
22720 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65  the.**     [powe
22730 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d  rsafe overwrite]
22740 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f   property does o
22750 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79  r does not apply
22760 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73   to the.**     s
22770 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20  torage media on 
22780 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61  which the databa
22790 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e  se file resides.
227a0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
227b0 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
227c0 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
227d0 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
227e0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
227f0 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
22800 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
22810 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
22820 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
22830 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
22840 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
22850 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
22860 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
22870 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
22880 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
22890 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
228a0 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
228b0 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
228c0 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
228d0 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
228e0 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
228f0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
22900 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
22910 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
22920 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
22930 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
22940 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
22950 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
22960 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
22970 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
22980 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
22990 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
229a0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
229b0 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
229c0 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
229d0 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
229e0 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
229f0 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
22a00 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
22a10 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
22a20 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
22a30 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
22a40 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
22a50 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
22a60 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
22a70 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22a80 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
22a90 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
22aa0 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
22ab0 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
22ac0 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
22ad0 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
22ae0 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
22af0 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
22b00 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
22b10 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
22b20 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
22b30 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
22b40 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
22b50 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
22b60 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
22b70 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
22b80 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
22b90 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
22ba0 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
22bb0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
22bc0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
22bd0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
22be0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
22bf0 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
22c00 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
22c10 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22c20 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
22c30 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
22c40 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
22c50 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
22c60 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
22c70 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
22c80 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
22c90 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
22ca0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
22cb0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
22cc0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
22cd0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
22ce0 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
22cf0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
22d00 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
22d10 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
22d20 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
22d30 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
22d40 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
22d50 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
22d60 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
22d70 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
22d80 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
22d90 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
22da0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
22db0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
22dc0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
22dd0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
22de0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22df0 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
22e00 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
22e10 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
22e20 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
22e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22e40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
22e50 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
22e60 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
22e70 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
22e80 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
22e90 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
22ea0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
22eb0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
22ec0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
22ed0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
22ee0 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
22ef0 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
22f00 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
22f10 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
22f20 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
22f30 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
22f40 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
22f50 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
22f60 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
22f70 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
22f80 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
22f90 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
22fa0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
22fb0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
22fc0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
22fd0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
22fe0 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
22ff0 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
23000 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
23010 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
23020 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
23030 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
23040 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
23050 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
23060 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
23070 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
23080 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
23090 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
230a0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
230b0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
230c0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
230d0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
230e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
230f0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
23100 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
23110 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
23120 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
23130 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
23140 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
23150 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
23160 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
23170 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
23180 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
23190 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
231a0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
231b0 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
231c0 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
231d0 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
231e0 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
231f0 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
23200 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
23210 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
23220 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
23230 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23240 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
23250 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
23260 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
23270 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
23280 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
23290 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
232a0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
232b0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
232c0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
232d0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
232e0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
232f0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
23300 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
23310 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
23320 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
23330 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
23340 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
23350 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
23360 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
23370 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
23380 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
23390 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
233a0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
233b0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
233c0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
233d0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
233e0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
233f0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
23400 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
23410 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
23420 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
23430 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
23440 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
23450 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
23460 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
23470 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
23480 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
23490 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
234a0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
234b0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
234c0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
234d0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
234e0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
234f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
23500 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
23510 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
23520 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
23530 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
23540 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
23550 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
23560 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
23570 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
23580 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
23590 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
235a0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
235b0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
235c0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
235d0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
235e0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
235f0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
23600 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
23610 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
23620 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
23630 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
23640 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
23650 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
23660 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23670 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23680 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
23690 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
236a0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
236b0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
236c0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
236d0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
236e0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
236f0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
23700 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
23710 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
23720 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
23730 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
23740 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23750 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
23760 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
23770 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
23780 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
23790 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
237a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
237b0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
237c0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
237d0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
237e0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
237f0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
23800 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23810 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23820 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
23830 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
23840 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
23850 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
23860 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
23870 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
23880 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
23890 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
238a0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
238b0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
238c0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
238d0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
238e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
238f0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
23900 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
23910 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
23920 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
23930 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
23940 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
23950 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
23960 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
23970 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
23980 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
23990 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
239a0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
239b0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
239c0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
239d0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
239e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
239f0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
23a00 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
23a10 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
23a20 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
23a30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23a40 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
23a50 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
23a60 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
23a70 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
23a80 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
23a90 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
23aa0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
23ab0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
23ac0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
23ad0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
23ae0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
23af0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
23b00 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
23b10 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
23b20 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
23b30 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
23b40 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23b50 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
23b60 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
23b70 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
23b80 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
23b90 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
23ba0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
23bb0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
23bc0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
23bd0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
23be0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
23bf0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
23c00 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
23c10 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
23c20 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
23c30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
23c40 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
23c50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
23c60 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23c70 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
23c80 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
23c90 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
23ca0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
23cb0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
23cc0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
23cd0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
23ce0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
23cf0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23d00 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
23d10 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
23d20 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
23d30 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
23d40 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
23d50 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
23d60 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
23d70 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
23d80 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
23d90 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
23da0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
23db0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
23dc0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
23dd0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
23de0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
23df0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
23e00 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
23e10 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
23e20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
23e30 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
23e40 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
23e50 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
23e60 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
23e70 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
23e80 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
23e90 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
23ea0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
23eb0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
23ec0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
23ed0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
23ee0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
23ef0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
23f00 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
23f10 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
23f20 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
23f30 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
23f40 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
23f50 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
23f60 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
23f70 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
23f80 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
23f90 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
23fa0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
23fb0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
23fc0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
23fd0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
23fe0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
23ff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
24000 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
24010 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
24020 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
24030 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
24040 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
24050 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
24060 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
24070 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
24080 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
24090 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
240a0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
240b0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
240c0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
240d0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
240e0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
240f0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
24100 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
24110 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
24120 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
24130 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24140 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24150 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24160 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
24170 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49  r *zParam);.SQLI
24180 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24190 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
241a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
241b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
241c0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
241d0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
241e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
241f0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
24200 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
24210 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
24220 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
24230 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
24240 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
24250 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
24260 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
24270 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24280 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
24290 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
242a0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
242b0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
242c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
242d0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
242e0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
242f0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
24300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24310 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
24320 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
24330 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
24340 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
24350 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
24360 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
24370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
24380 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
24390 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
243a0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
243b0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
243c0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
243d0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
243e0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
243f0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
24400 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
24410 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
24420 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
24430 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
24440 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
24450 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
24460 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
24470 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
24480 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
24490 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
244a0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
244b0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
244c0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
244d0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
244e0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
244f0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
24500 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
24510 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
24520 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
24530 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
24540 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
24550 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
24560 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
24570 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
24580 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
24590 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
245a0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
245b0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
245c0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
245d0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
245e0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
245f0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
24600 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
24610 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
24620 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
24630 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
24640 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
24650 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
24660 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
24670 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
24680 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
24690 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
246a0 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
246b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
246c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
246d0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
246e0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
246f0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
24700 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
24710 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
24720 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
24730 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
24740 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
24750 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
24760 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
24770 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
24780 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
24790 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
247a0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
247b0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
247c0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
247d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
247e0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
247f0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
24800 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
24810 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
24820 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
24830 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
24840 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24850 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
24860 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
24870 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
24880 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
24890 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
248a0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
248b0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
248c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
248d0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
248e0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
248f0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
24900 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
24910 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
24920 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
24930 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
24940 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
24950 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
24960 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
24970 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
24980 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
24990 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
249a0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
249b0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
249c0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
249d0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
249e0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
249f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24a00 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
24a10 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
24a20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24a30 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
24a40 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
24a50 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
24a60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
24a70 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
24a80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
24a90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
24aa0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
24ab0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
24ac0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24ad0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
24ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24af0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
24b00 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
24b10 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
24b20 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
24b30 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
24b40 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
24b50 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
24b60 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
24b70 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
24b80 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
24b90 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
24ba0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
24bb0 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
24bc0 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
24bd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
24be0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
24bf0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
24c00 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
24c10 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
24c20 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
24c30 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
24c40 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
24c50 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
24c60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
24c70 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
24c80 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
24c90 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
24ca0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
24cb0 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
24cc0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
24cd0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
24ce0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
24cf0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
24d00 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
24d10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24d20 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
24d30 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
24d40 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
24d50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24d60 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
24d70 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
24d80 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
24d90 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
24da0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
24db0 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
24dc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24dd0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
24de0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
24df0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
24e00 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
24e10 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
24e20 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
24e30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
24e40 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24e50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
24e60 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
24e70 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
24e80 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
24e90 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
24ea0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
24eb0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
24ec0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
24ed0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
24ee0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
24ef0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
24f00 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
24f10 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
24f20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24f30 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
24f40 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
24f50 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
24f60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24f70 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
24f80 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
24f90 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
24fa0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
24fb0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
24fc0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
24fd0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24fe0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
24ff0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
25000 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
25010 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
25020 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
25030 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
25040 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
25050 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
25060 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
25070 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
25080 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
25090 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
250a0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
250b0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
250c0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
250d0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
250e0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
250f0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
25100 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
25110 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
25120 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
25130 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
25140 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
25150 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
25160 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
25170 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
25180 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
25190 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
251a0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
251b0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
251c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
251d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
251e0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
251f0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
25200 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
25210 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
25220 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
25230 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
25240 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
25250 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
25260 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
25270 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
25280 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
25290 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
252a0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
252b0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
252c0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
252d0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
252e0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
252f0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
25300 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
25310 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
25320 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
25330 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
25340 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
25350 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
25360 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
25370 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
25380 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
25390 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
253a0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
253b0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
253c0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
253d0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
253e0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
253f0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
25400 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
25410 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
25420 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
25430 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
25440 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
25450 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
25460 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
25470 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
25480 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
25490 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
254a0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
254b0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
254c0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
254d0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
254e0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
254f0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
25500 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
25510 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
25520 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
25530 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
25540 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
25550 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
25560 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
25570 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
25580 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
25590 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
255a0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
255b0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
255c0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
255d0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
255e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
255f0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
25600 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
25610 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
25620 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
25630 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
25640 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
25650 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
25660 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
25670 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
25680 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
25690 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
256a0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
256b0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
256c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
256d0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
256e0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
256f0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
25700 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
25710 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
25720 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
25730 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
25740 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
25750 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
25760 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
25770 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
25780 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
25790 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
257a0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
257b0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
257c0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
257d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
257e0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
257f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
25800 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
25810 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
25820 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
25830 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
25840 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
25850 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25860 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25870 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
25880 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25890 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
258a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
258b0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
258c0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
258d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
258e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
258f0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
25900 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
25910 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25920 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25930 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
25940 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
25950 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
25960 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
25970 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
25980 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25990 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
259a0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
259b0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
259c0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
259d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
259e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
259f0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
25a00 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
25a10 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
25a20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
25a30 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
25a40 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
25a50 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
25a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25a70 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
25a80 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
25a90 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
25aa0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
25ab0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25ac0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
25ad0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
25ae0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
25af0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25b00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
25b10 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
25b20 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25b30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25b40 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25b50 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
25b60 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
25b70 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
25b80 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
25b90 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
25ba0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
25bb0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
25bc0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
25bd0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
25be0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
25bf0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
25c00 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
25c10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25c20 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
25c30 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
25c40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
25c50 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
25c60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25c70 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
25c80 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
25c90 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
25ca0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25cb0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
25cc0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
25cd0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
25ce0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25cf0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
25d00 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
25d10 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
25d20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25d30 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
25d40 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
25d50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25d60 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
25d70 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
25d80 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
25d90 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
25da0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
25db0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
25dc0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
25dd0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25de0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25df0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
25e00 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
25e10 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25e20 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
25e30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
25e40 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
25e50 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
25e60 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
25e70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
25e80 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
25e90 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
25ea0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
25eb0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
25ec0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25ed0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
25ee0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
25ef0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
25f00 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
25f10 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
25f20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25f30 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
25f40 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
25f50 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25f60 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
25f70 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
25f80 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
25f90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25fa0 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
25fb0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
25fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25fd0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
25fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25ff0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
26000 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
26010 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
26020 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
26030 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
26040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26050 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
26060 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
26070 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
26080 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
26090 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
260a0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
260b0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
260c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
260d0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
260e0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
260f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26100 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
26110 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
26120 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
26130 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
26140 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
26150 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
26160 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
26170 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
26180 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
26190 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
261a0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
261b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
261c0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
261d0 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
261e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
261f0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
26200 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
26210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
26220 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
26230 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
26240 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
26250 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
26260 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
26270 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
26280 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
26290 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
262a0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
262b0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
262c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
262d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
262e0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
262f0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
26300 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
26310 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
26320 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
26330 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26340 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26350 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
26360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
26370 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
26380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26390 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
263a0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
263b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
263c0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
263d0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
263e0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
263f0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
26400 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
26410 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
26420 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
26430 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26440 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
26450 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
26460 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26470 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
26480 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26490 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
264a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
264b0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
264c0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
264d0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
264e0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
264f0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
26500 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
26510 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
26520 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
26530 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
26540 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
26550 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
26560 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
26570 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
26580 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
26590 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
265a0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
265b0 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
265c0 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
265d0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
265e0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
265f0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
26600 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
26610 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
26620 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
26630 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
26640 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
26650 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
26660 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
26670 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
26680 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
26690 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
266a0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
266b0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
266c0 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
266d0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
266e0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
266f0 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
26700 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
26710 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
26720 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
26730 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
26740 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
26750 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
26760 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
26770 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
26780 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
26790 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
267a0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
267b0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
267c0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
267d0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
267e0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
267f0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
26800 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
26810 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
26820 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
26830 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
26840 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
26850 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
26860 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
26870 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
26880 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
26890 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
268a0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
268b0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
268c0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
268d0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
268e0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
268f0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
26900 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
26910 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
26920 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
26930 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
26940 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
26950 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
26960 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
26970 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
26980 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
26990 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
269a0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
269b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
269c0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
269d0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
269e0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
269f0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
26a00 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
26a10 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26a20 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
26a30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
26a40 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
26a50 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
26a60 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
26a70 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
26a80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26a90 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
26aa0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
26ab0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
26ac0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
26ad0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
26ae0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
26af0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
26b00 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
26b10 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
26b20 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
26b30 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
26b40 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
26b50 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
26b60 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
26b70 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
26b80 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
26b90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
26ba0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
26bb0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
26bc0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
26bd0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
26be0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
26bf0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
26c00 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
26c10 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
26c20 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
26c30 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
26c40 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
26c50 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
26c60 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
26c70 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
26c80 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
26c90 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
26ca0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
26cb0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
26cc0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
26cd0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
26ce0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
26cf0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
26d00 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
26d10 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
26d20 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
26d30 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
26d40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26d50 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
26d60 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
26d70 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
26d80 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
26d90 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
26da0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
26db0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
26dc0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
26dd0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
26de0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
26df0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
26e00 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
26e10 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
26e20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
26e30 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
26e40 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
26e50 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
26e60 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
26e70 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
26e80 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
26e90 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
26ea0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26eb0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
26ec0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
26ed0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
26ee0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
26ef0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
26f00 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
26f10 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
26f20 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
26f30 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
26f40 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
26f50 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
26f60 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
26f70 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
26f80 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
26f90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
26fa0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
26fb0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
26fc0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
26fd0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
26fe0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
26ff0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
27000 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
27010 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
27020 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
27030 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
27040 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
27050 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
27060 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
27070 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
27080 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
27090 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
270a0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
270b0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
270c0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
270d0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
270e0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
270f0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
27100 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
27110 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
27120 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
27130 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
27140 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
27150 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
27160 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
27170 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
27180 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
27190 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
271a0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
271b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
271c0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
271d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
271e0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
271f0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
27200 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
27220 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27230 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27240 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27250 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
27260 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27270 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27280 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
27290 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
272a0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
272b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
272c0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
272d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
272e0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
272f0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27300 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
27310 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27320 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27330 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27340 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
27350 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27360 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27370 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
27380 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27390 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
273a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
273b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
273c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
273d0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
273e0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
273f0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
27400 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
27410 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
27420 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
27430 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
27440 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27450 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
27460 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
27470 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27480 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
27490 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
274a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
274b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
274c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
274d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
274e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
274f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
27500 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
27510 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
27520 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
27530 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
27540 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
27550 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
27560 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
27570 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
27580 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
27590 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
275a0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
275b0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
275c0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
275d0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
275e0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
275f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27610 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
27620 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
27630 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
27640 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27650 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
27660 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
27670 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
27680 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
27690 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
276a0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
276b0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
276c0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
276d0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
276e0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
276f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27700 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
27710 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27720 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27730 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27740 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
27750 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
27760 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
27770 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
27780 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
27790 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
277a0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
277b0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
277c0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
277d0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
277e0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
277f0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
27800 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
27810 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
27820 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27830 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
27840 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
27850 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27860 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27870 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
27880 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27890 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
278a0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
278b0 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
278c0 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
278d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
278e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
278f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27900 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
27910 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
27920 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
27930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
27940 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
27950 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
27960 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
27970 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
27980 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
27990 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
279a0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
279b0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
279c0 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
279d0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
279e0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
279f0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
27a00 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
27a10 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
27a20 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
27a30 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
27a40 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
27a50 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
27a60 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
27a70 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
27a80 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
27a90 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27aa0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
27ab0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
27ac0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
27ad0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
27ae0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
27af0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
27b00 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
27b10 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
27b20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
27b30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
27b40 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
27b50 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
27b60 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
27b70 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
27b80 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
27b90 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
27ba0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
27bb0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
27bc0 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
27bd0 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
27be0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
27bf0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
27c00 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
27c10 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
27c20 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
27c30 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
27c40 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
27c50 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
27c60 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
27c70 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
27c80 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
27c90 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
27ca0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
27cb0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
27cc0 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
27cd0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
27ce0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
27cf0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
27d00 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
27d10 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
27d20 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
27d30 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
27d40 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
27d50 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
27d60 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
27d70 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
27d80 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
27d90 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
27da0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
27db0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
27dc0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
27dd0 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
27de0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27df0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
27e00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
27e10 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
27e20 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
27e30 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
27e40 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
27e50 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
27e60 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
27e70 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
27e80 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
27e90 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
27ea0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
27eb0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
27ec0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
27ed0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
27ee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
27ef0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
27f00 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
27f10 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
27f20 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
27f30 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27f40 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
27f50 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
27f60 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
27f70 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
27f80 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
27f90 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
27fa0 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
27fb0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
27fc0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
27fd0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
27fe0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
27ff0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
28000 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
28010 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
28020 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
28030 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
28040 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
28050 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
28060 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
28070 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
28080 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
28090 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
280a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
280b0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
280c0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
280d0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
280e0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
280f0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
28100 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
28110 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
28120 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
28130 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
28140 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
28150 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
28160 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
28170 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28180 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
28190 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
281a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
281b0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
281c0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
281d0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
281e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
281f0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
28200 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28210 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
28220 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
28230 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28240 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
28250 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
28260 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
28270 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
28280 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
28290 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
282a0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
282b0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
282c0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
282d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
282e0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
282f0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
28300 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
28310 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
28320 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
28330 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28340 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
28350 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
28360 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
28370 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
28380 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
28390 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
283a0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
283b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
283c0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
283d0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
283e0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
283f0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
28400 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
28410 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
28420 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
28430 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
28440 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
28450 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
28460 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28470 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
28480 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
28490 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
284a0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
284b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
284c0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
284d0 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
284e0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
284f0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
28500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28510 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
28520 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
28530 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28550 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
28560 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
28570 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
28580 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
28590 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
285a0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
285b0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
285c0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
285d0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
285e0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
285f0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
28600 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
28610 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
28620 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
28630 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
28640 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
28650 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
28660 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
28670 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
28680 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
28690 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
286a0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
286b0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
286c0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
286d0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
286e0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
286f0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
28700 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
28710 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
28720 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
28730 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28740 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28750 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28760 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
28770 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
28780 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
28790 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
287a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
287b0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
287c0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
287d0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
287e0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
287f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28800 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
28810 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
28820 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28830 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
28840 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
28850 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
28860 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
28870 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
28880 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28890 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
288a0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
288b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
288c0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
288d0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
288e0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
288f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
28900 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
28910 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
28920 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
28930 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
28940 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
28950 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
28960 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
28970 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
28980 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
28990 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
289a0 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
289b0 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
289c0 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
289d0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
289e0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
289f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
28a00 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
28a10 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
28a20 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
28a30 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
28a40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28a50 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
28a60 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28a70 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
28a80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28a90 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
28aa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28ab0 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
28ac0 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
28ad0 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
28ae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28af0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
28b00 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
28b10 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
28b20 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
28b30 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
28b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
28b50 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
28b60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
28b70 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
28b80 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
28b90 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
28ba0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
28bb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28bd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28be0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
28bf0 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
28c00 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
28c10 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
28c20 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
28c30 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
28c40 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
28c50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
28c60 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
28c70 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
28c80 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
28c90 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
28ca0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
28cb0 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
28cc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28cd0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
28ce0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
28cf0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
28d00 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
28d10 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
28d20 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
28d30 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
28d40 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
28d50 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
28d60 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
28d70 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
28d80 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
28d90 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
28da0 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
28db0 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
28dc0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
28dd0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
28de0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
28df0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
28e00 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
28e10 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
28e20 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
28e30 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
28e40 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
28e50 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
28e60 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
28e70 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
28e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
28e90 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
28ea0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
28eb0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28ec0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28ed0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
28ee0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
28ef0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
28f00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
28f10 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
28f20 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
28f30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
28f40 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
28f50 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
28f60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
28f70 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
28f80 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
28f90 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
28fa0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
28fb0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
28fc0 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
28fd0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
28fe0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
28ff0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
29000 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
29010 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
29020 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
29030 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
29040 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
29050 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
29060 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
29070 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
29080 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
29090 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
290a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
290b0 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
290c0 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
290d0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
290e0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
290f0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
29100 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
29110 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
29120 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
29130 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
29140 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
29150 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
29160 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
29170 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
29180 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
29190 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
291a0 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
291b0 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
291c0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
291d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
291e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
291f0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
29200 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
29210 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
29220 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
29230 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
29240 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
29250 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
29260 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
29270 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
29280 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
29290 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
292a0 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
292b0 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
292c0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
292d0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
292e0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
292f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
29300 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
29310 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
29320 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
29330 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
29340 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
29350 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
29360 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
29370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
29380 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
29390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
293a0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
293b0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
293c0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
293d0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
293e0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
293f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29400 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
29410 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
29420 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
29430 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29440 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29450 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
29460 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
29470 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
29480 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
29490 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
294a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
294b0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
294c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
294d0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
294e0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
294f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29500 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
29510 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
29520 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
29530 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
29540 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
29550 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
29560 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
29570 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
29580 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
29590 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
295a0 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
295b0 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
295c0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
295d0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
295e0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
295f0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
29600 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
29610 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
29620 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
29630 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
29640 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
29650 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
29660 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
29670 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
29680 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29690 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
296a0 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
296b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
296c0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
296d0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
296e0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
296f0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
29700 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
29710 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
29720 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
29730 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
29740 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
29750 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
29760 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
29770 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
29780 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
29790 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
297a0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
297b0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
297c0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
297d0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
297e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
297f0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
29800 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
29810 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
29820 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
29830 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
29840 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
29850 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
29860 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
29870 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
29880 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
29890 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
298a0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
298b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
298c0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
298d0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
298e0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
298f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29900 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
29910 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
29920 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
29930 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
29940 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
29950 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
29960 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
29970 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
29980 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
29990 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
299a0 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
299b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
299c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
299d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
299e0 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
299f0 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
29a00 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
29a10 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
29a20 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
29a30 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
29a40 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
29a50 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
29a60 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
29a70 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
29a80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29a90 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
29aa0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
29ab0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
29ac0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
29ad0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
29ae0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
29af0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
29b00 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
29b10 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
29b20 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
29b30 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
29b40 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
29b50 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
29b60 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
29b70 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
29b80 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
29b90 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
29ba0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
29bb0 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
29bc0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
29bd0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
29be0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
29bf0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
29c00 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
29c10 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
29c20 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
29c30 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
29c40 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
29c50 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29c60 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
29c70 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
29c80 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
29c90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29ca0 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
29cb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29cc0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
29cd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
29ce0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
29cf0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
29d00 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
29d10 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
29d20 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
29d30 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
29d40 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
29d50 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
29d60 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
29d70 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
29d80 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
29d90 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
29da0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
29db0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
29dc0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
29dd0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
29de0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
29df0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
29e00 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
29e10 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
29e20 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
29e30 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
29e40 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
29e50 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
29e60 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
29e70 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
29e80 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
29e90 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
29ea0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
29eb0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
29ec0 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
29ed0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
29ee0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
29ef0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
29f00 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
29f10 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
29f20 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
29f30 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
29f40 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
29f50 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
29f60 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
29f70 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
29f80 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
29f90 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
29fa0 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
29fb0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
29fc0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
29fd0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29fe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29ff0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2a000 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a010 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a020 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2a030 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a040 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a050 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a070 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a080 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2a090 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2a0a0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2a0b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a0c0 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
2a0d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a0e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
2a0f0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2a100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a110 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2a120 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2a130 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2a140 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2a150 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2a160 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
2a170 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2a180 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2a190 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2a1a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a1b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2a1c0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2a1d0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2a1e0 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
2a1f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2a200 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
2a210 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  stmt*, int);.SQL
2a220 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2a230 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2a240 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
2a250 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
2a260 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a270 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a280 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a290 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2a2a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2a2b0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2a2c0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2a2d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a2e0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2a2f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a300 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2a310 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2a320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a330 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2a340 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
2a350 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
2a360 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2a380 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2a390 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2a3a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2a3b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a3c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2a3d0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2a3e0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
2a3f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a400 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2a410 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
2a420 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2a430 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2a440 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2a450 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2a460 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2a470 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2a480 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2a490 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2a4a0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2a4b0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2a4c0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2a4d0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2a4e0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2a4f0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2a500 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a510 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2a520 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2a530 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2a540 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2a550 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2a560 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2a570 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2a580 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2a590 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2a5a0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2a5b0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2a5c0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2a5d0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a5e0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2a5f0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2a600 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2a610 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2a620 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2a630 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2a640 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2a650 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a660 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2a670 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2a680 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a690 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2a6a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a6b0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2a6c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2a6d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a6e0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2a6f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2a700 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a710 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2a720 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
2a730 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2a740 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2a750 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
2a760 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2a770 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
2a780 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2a790 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
2a7a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2a7b0 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
2a7c0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2a7d0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2a7e0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2a7f0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
2a800 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
2a810 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
2a820 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2a830 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2a840 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2a850 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2a860 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
2a870 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
2a880 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
2a890 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
2a8a0 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
2a8b0 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
2a8c0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
2a8d0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
2a8e0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
2a8f0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
2a900 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
2a910 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
2a920 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
2a930 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
2a940 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
2a950 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2a960 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
2a970 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
2a980 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
2a990 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
2a9a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
2a9b0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
2a9c0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
2a9d0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2a9e0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
2a9f0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
2aa00 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
2aa10 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
2aa20 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
2aa30 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
2aa40 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
2aa50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2aa60 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2aa70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2aa80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2aa90 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2aaa0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2aab0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2aac0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2aad0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2aae0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2aaf0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2ab00 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2ab10 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2ab20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ab30 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2ab40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2ab50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ab60 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2ab70 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2ab80 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
2ab90 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2aba0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2abb0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2abc0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2abd0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2abe0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2abf0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2ac00 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2ac10 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2ac20 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2ac30 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2ac40 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2ac50 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2ac60 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2ac70 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2ac80 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2ac90 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2aca0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2acb0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2acc0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2acd0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2ace0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2acf0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2ad00 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2ad10 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2ad20 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2ad30 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2ad40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ad50 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2ad60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ad70 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2ad80 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2ad90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2ada0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2adb0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2adc0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2add0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2ade0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2adf0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2ae00 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ae10 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2ae20 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2ae30 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2ae40 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2ae50 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2ae60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2ae70 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2ae80 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2ae90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2aea0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2aeb0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2aec0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2aed0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c   to NULL..*/.SQL
2aee0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2aef0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2af00 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2af10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2af20 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2af30 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2af40 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2af50 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2af60 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2af70 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2af80 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2af90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2afa0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2afb0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2afc0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2afd0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2afe0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2aff0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2b000 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2b010 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b020 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2b030 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2b040 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2b050 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2b060 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b070 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b080 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2b090 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2b0a0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
2b0b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b0c0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2b0d0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2b0e0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2b0f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2b100 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2b110 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2b120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b130 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2b140 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b150 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2b160 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2b170 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2b180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2b190 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2b1a0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2b1b0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2b1c0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2b1d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2b1e0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2b1f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2b200 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2b210 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2b220 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2b230 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2b240 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2b250 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2b260 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2b270 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2b280 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2b290 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2b2a0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2b2b0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2b2c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2b2d0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2b2e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b2f0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2b300 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2b310 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2b320 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2b330 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2b340 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b350 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2b360 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2b370 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2b380 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2b390 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2b3a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b3b0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2b3c0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2b3d0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2b3e0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2b3f0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2b400 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2b410 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2b420 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2b430 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2b440 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2b450 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2b460 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2b470 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2b480 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2b490 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2b4a0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2b4b0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2b4c0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2b4d0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2b4e0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2b4f0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2b500 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2b510 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2b520 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2b530 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2b540 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2b550 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2b560 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  next..*/.SQLITE_
2b570 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2b580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b590 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2b5a0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
2b5b0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2b5c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b5d0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2b5e0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2b5f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b600 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2b610 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2b620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2b630 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2b640 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2b650 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2b660 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2b670 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2b680 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2b690 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2b6a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2b6b0 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2b6c0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2b6d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2b6e0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2b6f0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2b700 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2b710 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2b720 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2b730 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2b740 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2b750 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2b760 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2b770 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2b780 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2b790 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2b7a0 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2b7b0 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2b7c0 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2b7d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2b7e0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2b7f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b800 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2b810 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2b820 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b830 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2b840 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2b850 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2b860 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2b870 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2b880 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2b890 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2b8a0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2b8b0 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2b8c0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2b8d0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2b8e0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2b8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2b900 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2b910 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2b920 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2b930 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2b940 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2b950 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2b960 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2b970 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2b980 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2b990 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2b9a0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2b9b0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2b9c0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2b9d0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2b9e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2b9f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2ba00 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2ba10 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2ba20 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2ba30 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2ba40 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2ba50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2ba60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2ba70 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2ba80 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2ba90 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2baa0 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2bab0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2bac0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2bad0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2bae0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2baf0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2bb00 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2bb10 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2bb20 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2bb30 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2bb40 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2bb50 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2bb60 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2bb70 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2bb80 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2bb90 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2bba0 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2bbb0 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2bbc0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2bbd0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2bbe0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2bbf0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2bc00 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2bc10 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2bc20 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2bc30 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2bc40 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2bc50 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2bc60 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2bc70 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2bc80 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2bc90 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2bca0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2bcb0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2bcc0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2bcd0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2bce0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2bcf0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2bd00 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2bd10 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2bd20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2bd30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2bd40 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2bd50 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2bd60 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2bd70 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2bd80 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2bd90 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2bda0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2bdb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2bdc0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2bdd0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2bde0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2bdf0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2be00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2be10 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2be20 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2be30 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2be40 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2be50 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
2be60 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2be70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2be80 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2be90 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2bea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2beb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2bec0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2bed0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2bee0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2bef0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2bf00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bf10 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2bf20 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2bf30 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2bf40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2bf50 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2bf60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2bf70 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2bf80 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2bf90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2bfa0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2bfb0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2bfc0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2bfd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2bfe0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2bff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c000 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2c010 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2c020 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2c030 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2c040 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2c050 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2c060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2c070 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2c080 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2c090 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2c0a0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2c0b0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2c0c0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2c0d0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2c0e0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2c0f0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2c100 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2c110 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2c120 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2c130 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2c140 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2c150 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2c160 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2c170 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2c180 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2c190 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2c1a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2c1b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2c1c0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2c1d0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2c1e0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2c1f0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2c200 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2c210 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2c220 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2c230 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2c240 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2c250 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2c260 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2c270 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2c280 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2c290 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2c2a0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2c2b0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2c2c0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2c2d0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2c2e0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2c2f0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2c300 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2c310 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2c320 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2c330 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2c340 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2c350 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2c360 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2c370 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2c380 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2c390 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2c3a0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2c3b0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2c3c0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2c3d0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2c3e0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2c3f0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2c400 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2c410 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2c420 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2c430 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2c440 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2c450 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2c460 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2c470 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2c480 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2c490 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2c4a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2c4b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2c4c0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2c4d0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2c4e0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2c4f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2c500 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2c510 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2c520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2c530 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2c540 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2c550 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2c560 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2c570 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2c580 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2c590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c5a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2c5b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2c5c0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2c5d0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2c5e0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2c5f0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2c600 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2c610 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2c620 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2c630 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2c640 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2c650 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2c660 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2c670 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2c680 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2c690 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2c6a0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2c6b0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2c6c0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2c6d0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2c6e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2c6f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c700 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2c710 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c720 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2c730 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2c740 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2c750 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2c760 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c770 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2c780 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2c790 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2c7a0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2c7b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2c7c0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2c7d0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2c7e0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2c7f0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2c800 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2c810 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2c820 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2c830 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2c840 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2c850 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2c860 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2c870 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2c880 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2c890 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2c8a0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2c8b0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2c8c0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2c8d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2c8e0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2c8f0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2c900 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2c910 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2c920 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2c930 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2c940 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2c950 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2c960 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2c970 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2c980 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2c990 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2c9a0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2c9b0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2c9c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2c9d0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2c9e0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2c9f0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2ca00 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2ca10 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2ca20 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2ca30 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2ca40 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2ca50 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2ca60 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2ca70 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2ca80 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2ca90 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2caa0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2cab0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2cac0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2cad0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2cae0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2caf0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2cb00 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2cb10 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2cb20 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2cb30 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2cb40 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2cb50 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2cb60 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2cb70 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2cb80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cb90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2cba0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2cbb0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2cbc0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2cbd0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2cbe0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2cbf0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2cc00 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2cc10 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2cc20 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2cc30 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2cc40 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2cc50 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2cc60 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2cc70 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2cc80 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2cc90 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2cca0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2ccb0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2ccc0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2ccd0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2cce0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2ccf0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2cd00 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2cd10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2cd20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2cd30 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2cd40 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2cd50 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2cd60 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2cd70 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2cd80 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2cd90 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2cda0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2cdb0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2cdc0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2cdd0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2cde0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2cdf0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2ce00 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2ce10 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2ce20 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2ce30 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ce40 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2ce50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ce60 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2ce70 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2ce80 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2ce90 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2cea0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2ceb0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2cec0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2ced0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2cee0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2cef0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2cf00 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2cf10 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2cf20 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2cf30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cf40 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2cf50 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2cf60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2cf70 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2cf80 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2cf90 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2cfa0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2cfb0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2cfc0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2cfd0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2cfe0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2cff0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2d000 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2d010 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2d020 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2d030 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2d040 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2d050 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2d060 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2d070 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2d080 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2d090 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d0a0 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2d0b0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2d0c0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2d0d0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2d0e0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d0f0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2d100 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2d110 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2d120 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d130 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2d140 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d150 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2d160 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d170 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2d180 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2d190 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2d1a0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2d1b0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2d1c0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2d1d0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2d1e0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2d1f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d200 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2d210 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2d220 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2d230 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2d240 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d250 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2d260 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2d270 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2d280 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2d290 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2d2a0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2d2b0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2d2c0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2d2d0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2d2e0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2d2f0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2d300 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2d310 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2d320 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2d330 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2d340 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2d350 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2d360 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2d370 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2d380 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2d390 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2d3a0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2d3b0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2d3c0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2d3d0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2d3e0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2d3f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2d400 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d410 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2d420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d430 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2d440 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2d450 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2d460 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2d470 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2d480 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2d490 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2d4a0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2d4b0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2d4c0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2d4d0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2d4e0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2d4f0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2d500 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2d510 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2d520 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2d530 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2d540 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d550 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2d560 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d570 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2d580 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2d590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2d5a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2d5b0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2d5c0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2d5d0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2d5e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2d5f0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2d600 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2d610 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2d620 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2d630 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2d640 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
2d650 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2d660 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2d670 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2d680 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2d690 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2d6a0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2d6b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2d6c0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2d6d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2d6e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2d6f0 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2d700 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2d710 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2d720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d730 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2d740 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d750 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2d760 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2d770 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2d780 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2d790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2d7a0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2d7b0 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2d7c0 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2d7d0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2d7e0 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2d7f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d800 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2d810 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2d820 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2d830 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2d840 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2d850 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2d860 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2d870 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2d880 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2d890 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2d8a0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2d8b0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2d8c0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2d8d0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2d8e0 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2d8f0 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2d900 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2d910 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2d920 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2d930 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2d940 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2d950 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2d960 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2d970 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2d980 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2d990 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2d9a0 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2d9b0 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2d9c0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2d9d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2d9e0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2d9f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2da00 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2da10 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2da20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2da30 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2da40 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2da50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2da60 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2da70 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2da80 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2da90 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2daa0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2dab0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2dac0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2dad0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2dae0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2daf0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2db00 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2db10 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2db20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2db30 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2db40 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2db50 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2db60 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2db70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2db80 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2db90 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2dba0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2dbb0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2dbc0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2dbd0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2dbe0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2dbf0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2dc00 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2dc10 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2dc20 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2dc30 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2dc40 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2dc50 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2dc60 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2dc70 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2dc80 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2dc90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2dca0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2dcb0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2dcc0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2dcd0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2dce0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2dcf0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2dd00 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2dd10 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2dd20 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2dd30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2dd40 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2dd50 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2dd60 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2dd70 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2dd80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2dd90 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
2dda0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
2ddb0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
2ddc0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2ddd0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2dde0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2ddf0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2de00 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2de10 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2de20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2de30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2de40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2de50 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2de60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2de70 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2de80 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2de90 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2dea0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2deb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2dec0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2ded0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2dee0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2def0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2df00 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2df10 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2df20 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2df30 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2df40 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2df50 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2df60 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2df70 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2df80 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2df90 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2dfa0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2dfb0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2dfc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2dfd0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2dfe0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2dff0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2e000 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2e010 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2e020 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2e030 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2e040 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2e050 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2e060 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2e070 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2e080 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2e090 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2e0a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2e0b0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2e0c0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2e0d0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2e0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2e0f0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2e100 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2e110 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2e120 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2e130 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2e140 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2e150 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2e160 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2e170 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2e180 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2e190 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e1a0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2e1b0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2e1c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2e1d0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2e1e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2e1f0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2e200 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2e210 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2e220 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e230 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2e240 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2e250 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2e260 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2e270 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2e280 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2e290 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2e2a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2e2b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2e2c0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2e2d0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2e2e0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2e2f0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2e300 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2e310 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2e320 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2e330 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2e340 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2e350 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2e360 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2e370 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2e380 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2e390 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2e3a0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2e3b0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2e3c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2e3d0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2e3e0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2e3f0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2e400 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2e410 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2e420 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2e430 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2e440 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2e450 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2e460 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2e470 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2e480 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2e490 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2e4a0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2e4b0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2e4c0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2e4d0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2e4e0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2e4f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e500 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2e510 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2e520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e530 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2e540 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2e550 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e560 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2e570 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e580 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2e590 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2e5a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e5b0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2e5c0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2e5d0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2e5e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2e5f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2e600 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e610 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2e620 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2e630 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2e640 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2e650 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2e660 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2e670 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2e680 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2e690 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2e6a0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2e6b0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e6c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2e6d0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2e6e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2e6f0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2e700 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e710 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2e720 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2e730 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2e740 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2e750 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2e760 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2e770 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2e780 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2e790 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e7a0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2e7b0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2e7c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e7d0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2e7e0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2e7f0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2e800 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e810 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2e820 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2e830 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2e840 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e850 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2e860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2e870 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2e880 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2e890 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2e8a0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2e8b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e8c0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2e8d0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2e8e0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2e8f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2e900 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2e910 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2e920 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2e930 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2e940 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e950 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2e960 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e970 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2e980 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2e990 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2e9a0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2e9b0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2e9c0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2e9d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2e9e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e9f0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2ea00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ea10 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2ea20 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2ea30 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2ea40 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2ea50 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2ea60 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2ea70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2ea80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2ea90 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2eaa0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2eab0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2eac0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2ead0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2eae0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2eaf0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2eb00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2eb10 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2eb20 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2eb30 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2eb40 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2eb50 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2eb60 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2eb70 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2eb80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2eb90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2eba0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
2ebb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2ebc0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
2ebd0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
2ebe0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2ebf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ec00 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2ec10 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
2ec20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ec30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
2ec40 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2ec50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2ec60 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
2ec70 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
2ec80 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
2ec90 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
2eca0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
2ecb0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
2ecc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2ecd0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2ece0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2ecf0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
2ed00 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2ed10 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
2ed20 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
2ed30 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2ed40 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
2ed50 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
2ed60 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
2ed70 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
2ed80 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
2ed90 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
2eda0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
2edb0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
2edc0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
2edd0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
2ede0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
2edf0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
2ee00 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
2ee10 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2ee20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2ee30 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2ee40 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2ee50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2ee60 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2ee70 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2ee80 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2ee90 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2eea0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2eeb0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2eec0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2eed0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2eee0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2eef0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2ef00 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2ef10 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2ef20 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2ef30 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2ef40 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2ef50 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2ef60 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2ef70 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2ef80 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2ef90 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
2efa0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2efb0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2efc0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2efd0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2efe0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2eff0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2f000 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2f010 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2f020 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2f030 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2f040 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2f050 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2f060 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2f070 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2f080 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2f090 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2f0a0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2f0b0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2f0c0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2f0d0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2f0e0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2f0f0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2f100 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2f110 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2f120 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f130 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
2f140 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2f150 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2f160 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2f170 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2f180 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
2f190 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f1a0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2f1b0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2f1c0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2f1d0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
2f1e0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2f1f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f200 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2f210 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2f220 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2f230 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2f240 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2f250 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2f260 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2f270 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
2f280 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
2f290 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
2f2a0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2f2b0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
2f2c0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
2f2d0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
2f2e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
2f2f0 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
2f300 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
2f310 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
2f320 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
2f330 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2f340 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
2f350 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
2f360 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
2f370 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
2f380 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
2f390 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
2f3a0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
2f3b0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
2f3c0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
2f3d0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
2f3e0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
2f3f0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
2f400 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2f410 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
2f420 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
2f430 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
2f440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f450 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
2f460 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
2f470 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2f480 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
2f490 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
2f4a0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
2f4b0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
2f4c0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
2f4d0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
2f4e0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2f4f0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
2f500 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2f510 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2f520 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
2f530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f540 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2f550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f560 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2f570 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
2f580 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
2f590 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
2f5a0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
2f5b0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2f5c0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2f5d0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
2f5e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f5f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
2f600 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2f610 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2f620 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2f630 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2f640 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2f650 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
2f660 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2f670 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2f680 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
2f690 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f6a0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
2f6b0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2f6c0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
2f6d0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2f6e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2f6f0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2f700 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
2f710 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
2f720 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2f730 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2f740 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2f750 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2f760 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2f770 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2f780 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2f790 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2f7a0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2f7b0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2f7c0 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
2f7d0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
2f7e0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2f7f0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2f800 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2f810 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2f820 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2f830 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2f840 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2f850 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2f860 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2f870 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2f880 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2f890 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2f8a0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2f8b0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2f8c0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2f8d0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2f8e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2f8f0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2f900 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2f910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f920 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2f930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f940 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2f950 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2f960 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2f970 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2f980 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2f990 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2f9a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f9b0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2f9c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f9d0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2f9e0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2f9f0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2fa00 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2fa10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2fa20 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2fa30 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2fa40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fa50 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2fa60 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2fa70 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2fa80 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2fa90 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2faa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fab0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2fac0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2fad0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2fae0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2faf0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2fb00 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2fb10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2fb20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fb30 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2fb40 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2fb50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2fb60 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2fb70 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2fb80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2fb90 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2fba0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2fbb0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2fbc0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
2fbd0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
2fbe0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
2fbf0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2fc00 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
2fc10 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
2fc20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fc30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2fc40 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2fc50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2fc60 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
2fc70 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2fc80 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2fc90 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2fca0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2fcb0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2fcc0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2fcd0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2fce0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
2fcf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2fd00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2fd10 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2fd20 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2fd30 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2fd40 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2fd50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2fd60 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2fd70 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2fd80 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2fd90 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2fda0 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2fdb0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2fdc0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2fdd0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2fde0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2fdf0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2fe00 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2fe10 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2fe20 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2fe30 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2fe40 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2fe50 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2fe60 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
2fe70 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2fe80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2fe90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2fea0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2feb0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2fec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fed0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
2fee0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2fef0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2ff00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ff10 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ff20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2ff30 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73  ITE_API double s
2ff40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2ff50 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2ff60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2ff70 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ff80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2ff90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ffa0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2ffb0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
2ffc0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
2ffd0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
2ffe0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fff0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
30000 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
30010 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30020 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
30030 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30040 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30050 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30060 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
30070 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30080 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
30090 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
300a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
300b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
300c0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
300d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
300e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
300f0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
30100 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
30110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
30120 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
30130 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
30140 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
30150 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30160 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
30170 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
30180 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30190 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
301a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
301b0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
301c0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
301d0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
301e0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
301f0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
30200 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
30210 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
30220 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
30230 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
30240 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30250 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
30260 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
30270 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
30280 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
30290 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
302a0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
302b0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
302c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
302d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
302e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
302f0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
30300 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
30310 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
30320 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
30330 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30340 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
30350 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
30360 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
30370 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
30380 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
30390 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
303a0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
303b0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
303c0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
303d0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
303e0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
303f0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
30400 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
30410 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
30420 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
30430 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
30440 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
30450 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
30460 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
30470 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
30480 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
30490 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
304a0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
304b0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
304c0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
304d0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
304e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
304f0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
30500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30510 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
30520 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
30530 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
30540 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
30550 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
30560 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
30570 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
30580 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
30590 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
305a0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
305b0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
305c0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
305d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
305e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
305f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30610 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
30620 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
30630 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
30640 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
30650 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
30660 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
30670 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30680 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
30690 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
306a0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
306b0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
306c0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
306d0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
306e0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
306f0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
30700 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
30710 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
30720 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
30730 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
30740 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
30750 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
30760 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
30770 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
30780 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
30790 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
307a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
307b0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
307c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
307d0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
307e0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
307f0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
30800 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30810 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30820 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
30830 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
30840 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
30850 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
30860 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
30870 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
30880 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
30890 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
308a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
308b0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
308c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
308d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
308e0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
308f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
30900 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30910 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
30920 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30930 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
30940 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
30950 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
30960 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
30970 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
30980 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
30990 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
309a0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
309b0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
309c0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
309d0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
309e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
309f0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
30a00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30a10 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
30a20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30a30 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
30a40 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
30a50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
30a60 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
30a70 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
30a80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
30a90 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
30aa0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
30ab0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
30ac0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
30ad0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
30ae0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
30af0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
30b00 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
30b10 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
30b20 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
30b30 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
30b40 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
30b50 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
30b60 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
30b70 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
30b80 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
30b90 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
30ba0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
30bb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
30bc0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
30bd0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
30be0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
30bf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30c00 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
30c10 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
30c20 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
30c30 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
30c40 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
30c50 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
30c60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
30c70 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
30c80 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
30c90 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
30ca0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30cb0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
30cc0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
30cd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
30ce0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30cf0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
30d00 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
30d10 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
30d20 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
30d30 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
30d40 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
30d50 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
30d60 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
30d70 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30d80 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
30d90 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
30da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30db0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
30dc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
30dd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
30de0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
30df0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
30e00 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
30e10 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
30e20 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
30e30 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
30e40 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
30e50 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
30e60 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
30e70 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
30e80 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
30e90 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
30ea0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
30eb0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
30ec0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
30ed0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
30ee0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
30ef0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
30f00 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
30f10 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
30f20 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
30f30 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
30f40 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
30f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
30f60 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
30f70 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
30f80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
30f90 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
30fa0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30fb0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
30fc0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
30fd0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
30fe0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
30ff0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
31000 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
31010 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31020 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
31030 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
31040 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
31050 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
31060 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
31070 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
31080 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
31090 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
310a0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
310b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
310c0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
310d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
310e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
310f0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
31100 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
31110 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
31120 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
31130 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
31140 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
31150 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
31160 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
31170 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
31180 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
31190 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
311a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
311b0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
311c0 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
311d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
311e0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
311f0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
31200 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
31210 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
31220 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
31230 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
31240 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
31250 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
31260 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
31270 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
31280 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
31290 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
312a0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
312b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
312c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
312d0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
312e0 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
312f0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31300 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
31310 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
31320 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
31330 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
31340 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
31350 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31360 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
31370 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
31380 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
31390 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
313a0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
313b0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
313c0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
313d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
313e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
313f0 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
31400 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
31410 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
31420 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
31430 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
31440 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
31450 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
31460 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
31470 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
31480 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
31490 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
314a0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
314b0 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
314c0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
314d0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
314e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
314f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
31500 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
31510 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
31520 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
31530 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
31540 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
31550 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
31560 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
31570 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
31580 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
31590 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
315a0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
315b0 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
315c0 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
315d0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
315e0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
315f0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
31600 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
31610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31620 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
31630 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
31640 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
31650 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
31660 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
31670 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
31680 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
31690 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
316a0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
316b0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
316c0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
316d0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
316e0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
316f0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31700 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31710 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
31720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
31730 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
31740 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
31750 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
31760 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
31770 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
31780 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
31790 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
317a0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
317b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
317c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
317d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
317e0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
317f0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
31800 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
31810 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
31820 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
31830 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
31840 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
31850 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
31860 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
31870 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
31880 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
31890 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
318a0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
318b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
318c0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
318d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
318e0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
318f0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
31900 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
31910 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
31920 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
31930 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
31940 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
31950 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
31960 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
31970 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
31980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31990 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
319a0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
319b0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
319c0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
319d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
319e0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
319f0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
31a00 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
31a10 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
31a20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
31a30 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
31a40 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
31a50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
31a60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
31a70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
31a80 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
31a90 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
31aa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31ab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31ac0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
31ad0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
31ae0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
31af0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
31b00 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
31b10 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
31b20 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
31b30 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
31b40 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
31b50 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
31b60 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
31b70 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
31b80 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
31b90 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
31ba0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
31bb0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
31bc0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
31bd0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
31be0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
31bf0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
31c00 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
31c10 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
31c20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
31c30 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
31c40 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
31c50 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
31c60 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
31c70 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
31c80 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
31c90 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
31ca0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
31cb0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
31cc0 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
31cd0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
31ce0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
31cf0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31d00 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
31d10 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
31d20 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
31d30 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
31d40 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
31d50 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
31d60 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
31d70 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
31d80 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
31d90 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
31da0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
31db0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
31dc0 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
31dd0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
31de0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
31df0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
31e00 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
31e10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
31e20 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
31e30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31e40 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
31e50 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
31e60 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
31e70 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
31e80 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
31e90 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
31ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
31eb0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
31ec0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
31ed0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
31ee0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
31ef0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
31f00 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
31f10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31f20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31f30 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
31f40 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
31f50 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
31f60 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
31f70 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
31f80 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
31f90 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
31fa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31fb0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31fc0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
31fd0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
31fe0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31ff0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32000 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
32010 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
32020 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
32030 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32040 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
32050 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
32060 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
32070 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
32080 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
32090 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
320a0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
320b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
320c0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
320d0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
320e0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
320f0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32100 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32110 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
32120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32130 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
32140 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32150 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
32160 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
32170 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
32180 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
32190 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
321a0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
321b0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
321c0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
321d0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
321e0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
321f0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
32200 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32210 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32220 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
32230 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
32240 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
32250 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
32260 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32270 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
32280 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
32290 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
322a0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
322b0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
322c0 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
322d0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
322e0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
322f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32300 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
32310 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
32320 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
32330 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
32340 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
32350 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
32360 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
32370 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
32380 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
32390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
323a0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
323b0 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65      /* Deprecate
323c0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
323d0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
323e0 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
323f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32400 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
32410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
32420 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a  ction Flags.**.*
32430 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
32440 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f  s may be ORed to
32450 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20  gether with the 
32460 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
32470 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78   | preferred tex
32480 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74  t encoding] as t
32490 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
324a0 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
324b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
324c0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
324d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
324e0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
324f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32500 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64  ion_v2()]..*/.#d
32510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
32520 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78  ERMINISTIC    0x
32530 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
32540 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
32550 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
32560 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
32570 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
32580 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
32590 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
325a0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
325b0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
325c0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
325d0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
325e0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
325f0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
32600 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
32610 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
32620 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
32630 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
32640 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
32650 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
32660 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
32670 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
32680 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
32690 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
326a0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
326b0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
326c0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
326d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
326e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
326f0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
32700 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
32710 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
32720 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
32730 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
32740 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
32750 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
32760 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
32770 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32780 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
32790 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
327a0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
327b0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
327c0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
327d0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
327e0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
327f0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
32800 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
32810 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
32820 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
32830 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
32840 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
32850 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32860 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
32870 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
32880 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
32890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
328a0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
328b0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
328c0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
328d0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
328e0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
328f0 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
32900 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
32910 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
32920 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
32930 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
32940 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
32950 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
32960 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
32970 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
32980 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
32990 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
329a0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
329b0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
329c0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
329d0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
329e0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
329f0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
32a00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32a10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32a20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32a30 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
32a40 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
32a50 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
32a60 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
32a70 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
32a80 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
32a90 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
32aa0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
32ab0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
32ac0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32ad0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32ae0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
32af0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32b00 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
32b10 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
32b20 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
32b30 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
32b40 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
32b50 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
32b60 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
32b70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32b80 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
32b90 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
32ba0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
32bb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32bc0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
32bd0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
32be0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32bf0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
32c00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32c10 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
32c20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
32c30 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
32c40 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
32c50 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
32c60 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32c70 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
32c80 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
32c90 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65  xcept that these
32ca0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
32cb0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
32cc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32cd0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
32ce0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
32cf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
32d00 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
32d10 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
32d20 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
32d30 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
32d40 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
32d50 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
32d60 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
32d70 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
32d80 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
32d90 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
32da0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
32db0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
32dc0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
32dd0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
32de0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
32df0 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
32e00 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
32e10 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
32e20 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
32e30 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
32e40 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
32e50 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
32e60 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
32e70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
32e80 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
32e90 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
32ea0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
32eb0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
32ec0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
32ed0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
32ee0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
32ef0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
32f00 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
32f10 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
32f20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
32f30 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
32f40 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
32f50 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
32f60 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
32f70 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
32f80 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
32f90 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
32fa0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
32fb0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
32fc0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
32fd0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
32fe0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
32ff0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
33000 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
33010 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
33020 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
33030 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
33040 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
33050 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
33060 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
33070 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33080 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
33090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
330a0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
330b0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
330c0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
330d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
330e0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
330f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33100 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
33110 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
33120 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
33130 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
33140 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
33150 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
33160 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
33170 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
33180 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33190 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
331a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
331b0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
331c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
331d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
331e0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
331f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
33200 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
33210 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
33220 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33230 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33240 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
33250 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
33260 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
33270 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
33280 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
33290 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
332a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
332b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
332c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
332d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
332e0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
332f0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
33300 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33310 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
33320 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
33330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33340 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
33350 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
33360 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33370 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
33380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33390 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
333a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
333b0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
333c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
333d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
333e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
333f0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
33400 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
33410 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
33420 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
33430 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33440 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33450 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
33460 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
33470 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
33480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
33490 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
334a0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
334b0 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
334c0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
334d0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
334e0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
334f0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
33500 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
33510 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
33520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
33530 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
33540 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33550 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
33560 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
33570 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
33580 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
33590 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
335a0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
335b0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
335c0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
335d0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
335e0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
335f0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
33600 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
33610 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
33620 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33630 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
33640 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
33650 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
33660 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
33670 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
33680 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
33690 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
336a0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
336b0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
336c0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
336d0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
336e0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
336f0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
33700 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
33710 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
33720 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
33730 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
33740 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
33750 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
33760 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
33770 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33780 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
33790 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
337a0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
337b0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
337c0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
337d0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
337e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
337f0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
33800 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
33810 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
33820 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
33830 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
33840 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
33850 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33860 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
33870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
33880 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
33890 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
338a0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
338b0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
338c0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
338d0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
338e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
338f0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
33900 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
33910 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33920 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
33930 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
33940 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
33950 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
33960 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
33970 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
33980 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
33990 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
339a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
339b0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
339c0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
339d0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
339e0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
339f0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
33a00 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
33a10 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
33a20 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
33a30 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
33a40 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
33a50 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
33a60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33a70 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
33a80 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
33a90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
33aa0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
33ab0 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
33ac0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
33ad0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
33ae0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
33af0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33b00 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
33b10 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
33b20 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
33b30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
33b40 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
33b50 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
33b60 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
33b70 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
33b80 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
33b90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
33ba0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
33bb0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
33bc0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
33bd0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
33be0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
33bf0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
33c00 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
33c10 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
33c20 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
33c30 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
33c40 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
33c50 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
33c60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
33c70 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
33c80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
33c90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33ca0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
33cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
33cc0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
33cd0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
33ce0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
33cf0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
33d00 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
33d10 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
33d20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
33d30 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
33d40 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
33d50 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
33d60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33d70 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
33d80 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
33d90 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
33da0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
33db0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
33dc0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
33dd0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
33de0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
33df0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
33e00 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
33e10 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
33e20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
33e30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33e40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
33e50 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
33e60 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
33e70 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
33e80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33e90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33ea0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
33eb0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
33ec0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
33ed0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
33ee0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
33ef0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33f00 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
33f10 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
33f20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33f30 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
33f40 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
33f50 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
33f60 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
33f70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
33f80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33f90 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
33fa0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
33fb0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
33fc0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
33fd0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53  d function..*/.S
33fe0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
33ff0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
34000 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
34010 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34030 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
34040 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
34050 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
34060 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
34070 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
34080 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
34090 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
340a0 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
340b0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
340c0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
340d0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
340e0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
340f0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
34100 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
34110 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
34120 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
34130 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
34140 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
34150 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
34160 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
34170 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
34180 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
34190 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
341a0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
341b0 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e   matching.** fun
341c0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
341d0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
341e0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
341f0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f  ssion can be sto
34200 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
34210 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
34220 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  th the pattern s
34230 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e  tring.  .** Then
34240 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
34250 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72  pattern string r
34260 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c  emains the same,
34270 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  .** the compiled
34280 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
34290 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
342a0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
342b0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
342c0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
342d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
342e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
342f0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
34300 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
34310 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
34320 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
34330 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
34340 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
34350 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
34360 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
34370 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
34380 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34390 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72  nction. ^If ther
343a0 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
343b0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
343c0 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ith the function
343d0 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20   argument, this 
343e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
343f0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ata() interface.
34400 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ** returns a NUL
34410 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
34420 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
34430 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
34440 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  X) interface sav
34450 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61  es P as metadata
34460 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
34470 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
34480 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34490 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
344a0 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63  ^Subsequent.** c
344b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
344c0 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
344d0 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74   return P from t
344e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
344f0 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
34500 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63  xdata(C,N,P,X) c
34510 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64  all if the metad
34520 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c  ata is still val
34530 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66  id or.** NULL if
34540 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61   the metadata ha
34550 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64  s been discarded
34560 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68  ..** ^After each
34570 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
34580 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
34590 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73  ,P,X) where X is
345a0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51   not NULL,.** SQ
345b0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
345c0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
345d0 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20  function X with 
345e0 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63  parameter P exac
345f0 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65  tly.** once, whe
34600 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  n the metadata i
34610 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  s discarded..** 
34620 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
34630 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65  o discard the me
34640 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69  tadata at any ti
34650 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c  me, including: <
34660 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e  ul>.** <li> when
34670 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
34680 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
34690 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f  meter changes, o
346a0 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b  r.** <li> when [
346b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
346c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
346d0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
346e0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ed for the.**   
346f0 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
34700 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
34710 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  n sqlite3_set_au
34720 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b  xdata() is invok
34730 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20  ed again on the 
34740 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  same parameter, 
34750 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e  or.** <li> durin
34760 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  g the original s
34770 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34780 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61  ta() call when a
34790 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20   memory .**     
347a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
347b0 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29  r occurs. </ul>)
347c0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65  ^.**.** Note the
347d0 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20   last bullet in 
347e0 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65  particular.  The
347f0 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e   destructor X in
34800 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74   .** sqlite3_set
34810 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34820 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
34830 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  d immediately, b
34840 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c  efore the.** sql
34850 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34860 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65  () interface eve
34870 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63  n returns.  Henc
34880 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
34890 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c  xdata().** shoul
348a0 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72  d be called near
348b0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
348c0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
348d0 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a  ntation and the.
348e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ** function impl
348f0 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
34900 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75  d not make any u
34910 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a  se of P after.**
34920 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34930 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20  data() has been 
34940 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  called..**.** ^(
34950 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
34960 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
34970 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
34980 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
34990 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
349a0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f  ters that are co
349b0 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74  mpile-time const
349c0 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ants, including 
349d0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
349e0 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
349f0 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f  s] and expressio
34a00 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d  ns composed from
34a10 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a   the same.)^.**.
34a20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
34a30 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
34a40 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
34a50 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
34a60 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
34a70 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
34a80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
34a90 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
34aa0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34ab0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
34ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
34ad0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34ae0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
34af0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
34b00 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
34b10 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
34b20 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
34b30 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
34b40 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
34b50 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
34b60 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
34b70 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
34b80 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
34b90 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
34ba0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
34bb0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
34bc0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
34bd0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
34be0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
34bf0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
34c00 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
34c10 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
34c20 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
34c30 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
34c40 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
34c50 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
34c60 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
34c70 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
34c80 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
34c90 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
34ca0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
34cb0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
34cc0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
34cd0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
34ce0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
34cf0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
34d00 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
34d10 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
34d20 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
34d30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
34d40 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
34d50 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
34d60 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
34d70 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
34d80 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ers..*/.typedef 
34d90 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
34da0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
34db0 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
34dc0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
34dd0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
34de0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
34df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
34e00 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
34e10 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
34e20 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
34e30 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
34e40 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
34e50 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
34e60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
34e70 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
34e80 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
34e90 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
34ea0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
34eb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
34ec0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
34ed0 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
34ee0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34ef0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34f00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
34f10 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
34f20 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
34f30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
34f40 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
34f50 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
34f60 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
34f70 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
34f80 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
34f90 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
34fa0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
34fb0 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
34fc0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
34fd0 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
34fe0 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
34ff0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
35000 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
35010 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
35020 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35030 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
35040 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
35050 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
35060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35070 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
35080 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
35090 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
350a0 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
350b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
350c0 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
350d0 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
350e0 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
350f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
35100 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35110 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
35120 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
35130 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
35140 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35150 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35160 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
35170 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
35180 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
35190 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
351a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
351b0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
351c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
351d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
351e0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
351f0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
35200 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
35210 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
35220 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35230 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
35240 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
35250 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
35260 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
35270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35280 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35290 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
352a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
352b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
352c0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
352d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
352e0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
352f0 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
35300 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
35310 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
35320 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
35330 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
35340 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
35350 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35360 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
35370 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
35380 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
35390 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
353a0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
353b0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
353c0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
353d0 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
353e0 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
353f0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
35400 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
35410 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35420 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
35430 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
35440 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
35450 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
35460 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
35470 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
35480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35490 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
354a0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
354b0 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
354c0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
354d0 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
354e0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
354f0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
35500 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
35510 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
35520 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35530 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
35540 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35550 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
35560 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
35570 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
35580 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
35590 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
355a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
355b0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
355c0 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
355d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
355e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
355f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
35600 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
35610 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
35620 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
35630 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
35640 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
35650 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
35660 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
35670 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
35680 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
35690 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
356a0 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
356b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
356c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
356d0 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
356e0 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
356f0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
35700 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
35710 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
35720 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
35730 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
35740 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
35750 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
35760 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
35770 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
35780 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35790 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
357a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
357b0 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
357c0 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
357d0 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
357e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
357f0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
35800 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
35810 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
35820 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
35830 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
35840 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
35850 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
35860 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
35870 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35880 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
35890 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
358a0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
358b0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
358c0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
358d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
358e0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
358f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35900 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
35910 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
35920 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
35930 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35940 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35950 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
35960 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
35970 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
35980 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
35990 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
359a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
359b0 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
359c0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
359d0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
359e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
359f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35a00 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
35a10 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
35a20 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
35a30 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
35a40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35a50 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
35a60 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35a70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
35a80 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
35a90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35aa0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
35ab0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
35ac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35ad0 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
35ae0 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
35af0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35b00 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
35b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b20 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
35b30 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
35b40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
35b50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35b60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35b70 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
35b80 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
35b90 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
35ba0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
35bb0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
35bc0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
35bd0 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
35be0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
35bf0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
35c00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35c10 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e  sult_text64() in
35c20 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35c30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35c40 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69   an.** applicati
35c50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35c60 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74  ion to be a text
35c70 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e   string in an en
35c80 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66  coding.** specif
35c90 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74 68  ied by the fifth
35ca0 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61   (and last) para
35cb0 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73  meter, which mus
35cc0 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b  t be one.** of [
35cd0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
35ce0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
35cf0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
35d00 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
35d10 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  LE]..** ^SQLite 
35d20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
35d30 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
35d40 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
35d50 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
35d60 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
35d70 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35d80 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
35d90 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
35da0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
35db0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35dc0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
35dd0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
35de0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
35df0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
35e00 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
35e10 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
35e20 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
35e30 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
35e40 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
35e50 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
35e60 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
35e70 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
35e80 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
35e90 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
35ea0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
35eb0 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
35ec0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
35ed0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
35ee0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
35ef0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35f00 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
35f10 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33  esult.  If the 3
35f20 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
35f30 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
35f40 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65  en it.** must be
35f50 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
35f60 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67   into the string
35f70 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
35f80 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a  erminator would.
35f90 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65  ** appear if the
35fa0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55   string where NU
35fb0 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  L terminated.  I
35fc0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
35fd0 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ters occur.** in
35fe0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61   the string at a
35ff0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61   byte offset tha
36000 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  t is less than t
36010 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
36020 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  3rd.** parameter
36030 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
36040 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c  ting string will
36050 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
36060 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a  d NULs and the.*
36070 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  * result of expr
36080 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e  essions operatin
36090 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74  g on strings wit
360a0 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
360b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
360c0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
360d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
360e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
360f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
36100 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
36110 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
36120 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
36130 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
36140 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
36150 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
36160 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
36170 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
36180 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
36190 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
361a0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
361b0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
361c0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
361d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
361e0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
361f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
36200 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
36210 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
36220 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
36230 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
36240 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
36250 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
36260 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
36270 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
36280 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
36290 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
362a0 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
362b0 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
362c0 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
362d0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
362e0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
362f0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
36300 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
36310 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
36320 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36330 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
36340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36350 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
36360 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
36370 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
36380 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
36390 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
363a0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
363b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
363c0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
363d0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
363e0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
363f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36400 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
36410 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36420 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
36430 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36440 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36450 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
36460 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
36470 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36480 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
36490 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
364a0 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
364b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
364c0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
364d0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
364e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
364f0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
36500 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
36510 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
36520 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
36530 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
36540 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
36550 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
36560 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
36570 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
36580 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
36590 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
365a0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
365b0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
365c0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
365d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
365e0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
365f0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
36600 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
36610 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36620 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
36630 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
36640 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
36650 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
36660 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
36670 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
36680 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
36690 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
366a0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
366b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
366c0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
366d0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
366e0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
366f0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
36700 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
36710 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
36720 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36730 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
36740 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
36750 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
36760 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
36770 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
36780 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36  te3_result_blob6
36790 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
367a0 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 73  t*,const void*,s
367b0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f  qlite3_uint64,vo
367c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
367d0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
367e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
367f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
36800 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
36810 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36820 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36830 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
36840 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36850 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  r*, int);.SQLITE
36860 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36870 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36880 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36890 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
368a0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
368b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
368c0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
368d0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
368e0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
368f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36900 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
36910 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36920 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
36930 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36940 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
36950 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36960 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
36970 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36980 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
36990 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
369a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
369b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
369c0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
369d0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
369e0 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
369f0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
36a00 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
36a10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
36a20 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36a30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36a40 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36a50 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36a60 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
36a70 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
36a80 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
36a90 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c  esult_text64(sql
36aa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36ab0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
36ac0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
36ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36ae0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
36af0 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
36b00 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53  har encoding);.S
36b10 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
36b20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36b30 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
36b40 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36b50 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
36b60 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
36b70 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36b80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
36b90 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
36ba0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36bb0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
36bc0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
36bd0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
36be0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
36bf0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36c00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36c10 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
36c20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
36c30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36c40 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
36c50 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
36c60 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36c70 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36c80 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
36c90 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
36ca0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
36cb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
36cc0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
36cd0 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
36ce0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
36cf0 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
36d00 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
36d10 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
36d20 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
36d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36d40 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
36d50 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
36d60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
36d70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
36d80 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
36d90 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
36da0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36db0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
36dc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36dd0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
36de0 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
36df0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
36e00 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
36e10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36e20 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
36e30 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
36e40 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
36e50 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
36e60 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
36e70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
36e80 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
36e90 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
36ea0 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
36eb0 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
36ec0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
36ed0 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
36ee0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
36ef0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
36f00 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
36f10 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
36f20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
36f30 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
36f40 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
36f50 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
36f60 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
36f70 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
36f80 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
36f90 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
36fa0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
36fb0 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
36fc0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36fd0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
36fe0 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
36ff0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
37000 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
37010 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
37020 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
37030 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
37040 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
37050 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
37060 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
37070 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
37080 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
37090 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
370a0 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
370b0 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
370c0 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
370d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
370e0 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
370f0 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
37100 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
37110 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
37120 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
37130 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
37140 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
37150 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
37160 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
37170 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
37180 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
37190 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
371a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
371b0 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
371c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
371d0 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
371e0 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
371f0 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
37200 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
37210 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
37220 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
37230 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
37240 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
37250 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
37260 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
37270 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
37280 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
37290 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
372a0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
372b0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
372c0 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
372d0 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
372e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
372f0 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
37300 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
37310 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
37320 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
37330 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
37340 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37350 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
37360 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
37370 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
37380 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
37390 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
373a0 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
373b0 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
373c0 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
373d0 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
373e0 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
373f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37400 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
37410 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
37420 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
37430 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
37440 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
37450 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
37460 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
37470 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
37480 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
37490 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
374a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
374b0 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
374c0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
374d0 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
374e0 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
374f0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
37500 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37510 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
37520 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
37530 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
37540 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
37550 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
37560 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
37570 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
37580 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
37590 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
375a0 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
375b0 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
375c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
375d0 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
375e0 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
375f0 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
37600 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
37610 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
37620 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
37630 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
37640 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
37650 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
37660 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
37670 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
37680 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
37690 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
376a0 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
376b0 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
376c0 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
376d0 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
376e0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
376f0 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
37700 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
37710 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
37720 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
37730 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
37740 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
37750 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
37760 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37770 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
37780 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
37790 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
377a0 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
377b0 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
377c0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
377d0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
377e0 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
377f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37800 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
37810 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
37820 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
37830 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
37840 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
37850 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
37860 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
37870 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
37880 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
37890 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
378a0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
378b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
378c0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
378d0 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
378e0 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
378f0 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
37900 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
37910 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37920 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
37930 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
37940 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
37950 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
37960 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
37970 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
37980 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
37990 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
379a0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
379b0 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
379c0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
379d0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
379e0 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
379f0 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
37a00 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
37a10 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
37a20 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
37a30 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
37a40 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
37a50 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
37a60 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
37a70 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
37a80 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
37a90 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
37aa0 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
37ab0 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
37ac0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
37ad0 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
37ae0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37af0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
37b00 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37b10 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ed16()]..*/.SQLI
37b20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37b30 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37b40 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
37b50 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
37b60 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
37b70 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
37b80 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
37b90 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
37ba0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37bb0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
37bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37bd0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37be0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
37bf0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
37c00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
37c10 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
37c20 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
37c30 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
37c40 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
37c50 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
37c60 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
37c70 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
37c80 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
37c90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37ca0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
37cb0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
37cc0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
37cd0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
37ce0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
37cf0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
37d00 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
37d10 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37d20 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
37d30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
37d40 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
37d50 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
37d60 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
37d70 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
37d80 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37d90 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
37da0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
37db0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
37dc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
37dd0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
37de0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
37df0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37e00 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
37e10 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
37e20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
37e30 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
37e40 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
37e50 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
37e60 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
37e70 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
37e80 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37e90 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
37ea0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
37eb0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
37ec0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
37ed0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
37ee0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
37ef0 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
37f00 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37f10 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
37f20 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
37f30 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
37f40 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
37f50 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
37f60 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
37f70 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
37f80 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
37f90 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
37fa0 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
37fb0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
37fc0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
37fd0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
37fe0 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
37ff0 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
38000 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
38010 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
38020 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
38030 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
38040 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
38050 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
38060 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
38070 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
38080 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
38090 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
380a0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
380b0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
380c0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
380d0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
380e0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
380f0 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
38100 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
38110 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
38120 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
38130 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
38140 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
38150 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
38160 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
38170 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
38180 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
38190 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
381a0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
381b0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
381c0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
381d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
381e0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
381f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38200 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
38210 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
38220 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
38230 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
38240 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
38250 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
38260 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
38270 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
38280 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
38290 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
382a0 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54   char*).);.SQLIT
382b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
382c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
382d0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
382e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
382f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
38300 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
38310 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
38320 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
38330 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
38340 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
38350 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
38360 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
38370 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
38380 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
38390 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
383a0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
383b0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
383c0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
383d0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
383e0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
383f0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
38400 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
38410 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  I int sqlite3_ke
38420 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
38430 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
38440 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38450 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
38460 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
38470 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
38480 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
38490 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
384a0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32  t sqlite3_key_v2
384b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
384c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
384d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
384e0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
384f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
38500 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
38510 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
38520 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
38530 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
38540 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
38550 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
38560 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
38570 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
38580 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
38590 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
385a0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
385b0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
385c0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
385d0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
385e0 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
385f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
38600 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
38610 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
38620 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
38630 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
38640 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
38650 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
38660 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
38670 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
38680 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
38690 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
386a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
386b0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
386c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
386d0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
386e0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
386f0 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  key */.);.SQLITE
38700 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
38710 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c  _rekey_v2(.  sql
38720 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
38730 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
38740 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
38750 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
38760 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
38770 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d            /* Nam