System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact df5a4608875ff83f7c3fa37c2169a55e5ba99a6e:


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 34 2e 31 22 0a 23 64 65 66 69 6e 65 20  .8.4.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 34 0a 23 64  UMBER 3008004.#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 30 33 2d 31 31 20 31 35 3a 32 37 3a 33 36  4-03-11 15:27:36
1080: 20 30 31 38 64 33 31 37 62 31 32 35 37 63 65 36   018d317b1257ce6
1090: 38 61 39 32 39 30 38 62 30 35 63 39 63 37 63 66  8a92908b05c9c7cf
10a0: 31 34 39 34 30 35 30 64 30 22 0a 0a 2f 2a 0a 2a  1494050d0"../*.*
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 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2b70: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2b80: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2b90: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ba0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2bb0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2bc0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2bd0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2be0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2bf0: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2c00: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2c10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2c20: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2c30: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2c40: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2c50: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2c60: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2c70: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2c80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2c90: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2ca0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2cb0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2cc0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2cd0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2ce0: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2cf0: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2d00: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2d10: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2d20: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2d30: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2d40: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2d50: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2d60: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2d70: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2d80: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2d90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2da0: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2db0: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2dc0: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2dd0: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2de0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2df0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2e00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2e10: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2e20: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2e30: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2e40: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2e50: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2e60: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2e70: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2e80: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2e90: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2ea0: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2eb0: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2ec0: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2ed0: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2ee0: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2ef0: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2f00: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2f10: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2f20: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2f30: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2f40: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2f50: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2f60: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2f70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2f80: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2f90: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2fa0: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2fd0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2fe0: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2ff0: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
3000: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
3010: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
3020: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
3030: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
3040: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
3050: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
3060: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
3070: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
3080: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
3090: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
30a0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
30b0: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
30c0: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
30d0: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
30e0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
30f0: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3100: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3110: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3120: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3130: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
3140: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
3150: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
3160: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
3170: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
3180: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
3190: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
31a0: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
31b0: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
31c0: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
31d0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
31e0: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
31f0: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3200: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3210: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3220: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3230: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
3240: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
3250: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
3260: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
3270: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
3280: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
3290: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
32a0: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
32b0: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
32c0: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
32d0: 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  -op..*/.SQLITE_A
32e0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
32f0: 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a  lose(sqlite3*);.
3300: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
3310: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
3320: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
3330: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
3340: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3350: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
3360: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
3370: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
3380: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
3390: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
33a0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
33b0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
33c0: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
33d0: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
33e0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
33f0: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
3400: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
3410: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
3420: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a  tion Interface.*
3430: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
3440: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3450: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
3460: 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e  ce wrapper aroun
3470: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  d.** [sqlite3_pr
3480: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
3490: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
34a0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
34b0: 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74  lize()],.** that
34c0: 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69   allows an appli
34d0: 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75  cation to run mu
34e0: 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74  ltiple statement
34f0: 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68  s of SQL.** with
3500: 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73  out having to us
3510: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
3520: 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e. .**.** ^The s
3530: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
3540: 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72  terface runs zer
3550: 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20  o or more UTF-8 
3560: 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69  encoded,.** semi
3570: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53  colon-separate S
3580: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3590: 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e  ssed into its 2n
35a0: 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69  d argument,.** i
35b0: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66  n the context of
35c0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35d0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65  onnection] passe
35e0: 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a  d in as its 1st.
35f0: 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49  ** argument.  ^I
3600: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  f the callback f
3610: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33  unction of the 3
3620: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  rd argument to.*
3630: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3640: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
3650: 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  en it is invoked
3660: 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74   for each result
3670: 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f   row.** coming o
3680: 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61  ut of the evalua
3690: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
36a0: 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  ts.  ^The 4th ar
36b0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
36c0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
36d0: 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74  elayed through t
36e0: 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65  o the 1st argume
36f0: 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61  nt of each.** ca
3700: 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f  llback invocatio
3710: 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  n.  ^If the call
3720: 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20  back pointer to 
3730: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3740: 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  * is NULL, then 
3750: 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65  no callback is e
3760: 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20  ver invoked and 
3770: 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a  result rows are.
3780: 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  ** ignored..**.*
3790: 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
37a0: 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c  ccurs while eval
37b0: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73  uating the SQL s
37c0: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
37d0: 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
37e0: 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78  _exec(), then ex
37f0: 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63  ecution of the c
3800: 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  urrent statement
3810: 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75   stops and.** su
3820: 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65  bsequent stateme
3830: 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e  nts are skipped.
3840: 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61    ^If the 5th pa
3850: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3860: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
3870: 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e  not NULL then an
3880: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  y error message 
3890: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
38a0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
38b0: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
38c0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70  _malloc()] and p
38d0: 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75  assed back throu
38e0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38f0: 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69  eter..** To avoi
3900: 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20  d memory leaks, 
3910: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
3920: 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73  should invoke [s
3930: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a  qlite3_free()].*
3940: 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  * on error messa
3950: 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ge strings retur
3960: 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ned through the 
3970: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  5th parameter of
3980: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  .** of sqlite3_e
3990: 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20  xec() after the 
39a0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
39b0: 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  ring is no longe
39c0: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66  r needed..** ^If
39d0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
39e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
39f0: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3a00: 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a   and no errors.*
3a10: 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71  * occur, then sq
3a20: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74  lite3_exec() set
3a30: 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  s the pointer in
3a40: 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74   its 5th paramet
3a50: 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65  er to.** NULL be
3a60: 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
3a70: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c  **.** ^If an sql
3a80: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3a90: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
3aa0: 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74  -zero, the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75  e3_exec().** rou
3ac0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c  tine returns SQL
3ad0: 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75  ITE_ABORT withou
3ae0: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63  t invoking the c
3af0: 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e  allback again an
3b00: 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e  d.** without run
3b10: 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75  ning any subsequ
3b20: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
3b30: 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32  ts..**.** ^The 2
3b40: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
3b50: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b60: 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  ) callback funct
3b70: 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  ion is the.** nu
3b80: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
3b90: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  in the result.  
3ba0: 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e  ^The 3rd argumen
3bb0: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3bc0: 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62  _exec().** callb
3bd0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3be0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3bf0: 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20  trings obtained 
3c00: 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73  as if from.** [s
3c10: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
3c20: 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65  xt()], one for e
3c30: 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66  ach column.  ^If
3c40: 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61   an element of a
3c50: 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69  .** result row i
3c60: 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
3c70: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74  corresponding st
3c80: 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72  ring pointer for
3c90: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3ca0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3cb0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3cc0: 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  r.  ^The 4th arg
3cd0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
3ce0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3cf0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d00: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d10: 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65  to strings where
3d20: 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72   each.** entry r
3d30: 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61  epresents the na
3d40: 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64  me of correspond
3d50: 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ing result colum
3d60: 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  n as obtained.**
3d70: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
3d80: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  olumn_name()]..*
3d90: 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64  *.** ^If the 2nd
3da0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3db0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3dc0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
3dd0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
3de0: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
3df0: 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68   or a pointer th
3e00: 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79  at contains only
3e10: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f   whitespace and/
3e20: 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65  or .** SQL comme
3e30: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c  nts, then no SQL
3e40: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3e50: 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68  evaluated and th
3e60: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  e database.** is
3e70: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a   not changed..**
3e80: 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73  .** Restrictions
3e90: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
3ea0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
3eb0: 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65  tion must insure
3ec0: 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61   that the 1st pa
3ed0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ee0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20  e3_exec().**    
3ef0: 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64    is a valid and
3f00: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
3f10: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
3f20: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
3f30: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c  tion must not cl
3f40: 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  ose the [databas
3f50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
3f60: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
3f70: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
3f80: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3f90: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3fa0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fb0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
3fc0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
3fd0: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
3fe0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
3ff0: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
4000: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
4010: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
4020: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4030: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4040: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4050: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
4060: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
4070: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
4080: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
40b0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
40c0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
40f0: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
4100: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
4110: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
4120: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
4130: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
4140: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
4150: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
4180: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
4190: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
41a0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
41d0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
41e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
41f0: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
4200: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
4210: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
4220: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
4230: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
4240: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
4250: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
4260: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4270: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4280: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4290: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
42a0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
42b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
42c0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
42d0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
42e0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
42f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4300: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4310: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4320: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
4330: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
4340: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4350: 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  codes],.** [sqli
4360: 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
4370: 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f  lict()] [SQLITE_
4380: 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c  ROLLBACK | resul
4390: 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65  t codes]..*/.#de
43a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
43b0: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
43c0: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
43d0: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
43e0: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
4410: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
4420: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
4430: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4440: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
4450: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
4460: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
4470: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
4480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
4490: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
44a0: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
44b0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
44d0: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
44e0: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
44f0: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
4500: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
4510: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
4520: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
4530: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
4540: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4550: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
4560: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
4570: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
4580: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
45a0: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
45b0: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
45c0: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
45d0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
45e0: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
45f0: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
4600: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
4610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4620: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
4630: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
4640: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
4650: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
4660: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
4670: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
4680: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
4690: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
46a0: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
46b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
46c0: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
46d0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
46e0: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
46f0: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
4700: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
4710: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b  D    12   /* Unk
4720: 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73  nown opcode in s
4730: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
4740: 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  rol() */.#define
4750: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4760: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4770: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4780: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4790: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
47a0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
47b0: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
47c0: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
47d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
47e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
47f0: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
4800: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
4810: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
4820: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4830: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
4840: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
4850: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4870: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4880: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4890: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
48b0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
48c0: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
48d0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
48e0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
48f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
4900: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
4910: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
4920: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
4940: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
4950: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4960: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4970: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4980: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4990: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
49a0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
49b0: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
49c0: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
49d0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
49e0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
49f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a00: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
4a10: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
4a20: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4a30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
4a40: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
4a50: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4a60: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a80: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4a90: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4aa0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4ab0: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4ac0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ad0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4ae0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4af0: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
4b00: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20  _NOTICE      27 
4b30: 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f    /* Notificatio
4b40: 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ns from sqlite3_
4b50: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  log() */.#define
4b60: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20   SQLITE_WARNING 
4b70: 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e      28   /* Warn
4b80: 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ings from sqlite
4b90: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
4ba0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4bb0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4bc0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4bd0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4be0: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4bf0: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4c00: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4c10: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4c20: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4c30: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4c40: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4c50: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4c60: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
4c70: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4c80: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4c90: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4ca0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4cb0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4cc0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4cd0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4ce0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4cf0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4d00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4d10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4d20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4d30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4d40: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4d50: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4d60: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4d70: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4d80: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4d90: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4da0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4db0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4dc0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4dd0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4de0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4df0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4e00: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4e10: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4e20: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4e30: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4e40: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4e50: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4e60: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4e70: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4e80: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4e90: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4ea0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4eb0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4ec0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4ed0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4ee0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4ef0: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f00: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f10: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f20: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f30: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4f40: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4f50: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4f60: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4f70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4f80: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4f90: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4fa0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4fb0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4fc0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e  lt codes will in
4fd0: 63 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74  crease.** over t
4fe0: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ff0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
5000: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
5010: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
5020: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
5030: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
5040: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
5050: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
5060: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
5070: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
5080: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5090: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
50a0: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
50b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
50c0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
50d0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
50f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5100: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5110: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5120: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5170: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5180: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5190: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51a0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
51b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51c0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
51d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
51e0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
51f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5200: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5210: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5220: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5240: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5250: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5260: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5280: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5290: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52a0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<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 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
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 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5410: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5420: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54c0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54e0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
54f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5500: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5510: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5520: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5530: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5540: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5550: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5560: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5570: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5580: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5590: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55a0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
55b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55c0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
55d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55e0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
55f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5600: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5610: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5620: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5630: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5640: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5650: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5660: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5670: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5680: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5690: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56a0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56c0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56e0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5700: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5710: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5720: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5730: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5740: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5750: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5760: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5780: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57a0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57c0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
57e0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
57f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5800: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5810: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5820: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5840: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5850: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5870: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5880: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5890: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58d0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
58f0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5900: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5910: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5930: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5940: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5950: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5970: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5980: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5990: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59a0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59b0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59d0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
59f0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a10: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a30: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a50: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a70: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a90: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5aa0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ac0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ad0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5ae0: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b00: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b20: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b60: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b80: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ba0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5be0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5bf0: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c10: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c30: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c70: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5c80: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c90: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cb0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5cc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5ce0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cf0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d00: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d20: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d30: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d40: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d60: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d80: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5da0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5db0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5dc0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5de0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5df0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5e00: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5e10: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5e20: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5e30: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5e40: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5e50: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5e60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5e70: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5e80: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5e90: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5ea0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5eb0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5ec0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ed0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5ee0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ef0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5f40: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5f50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5f60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f70: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5f80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5f90: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5fa0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5fb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fc0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5fd0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5fe0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5ff0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6000: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6010: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6020: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
6030: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6040: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
6050: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6060: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
6070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6080: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6090: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
60a0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
60b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60d0: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
60e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
60f0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
6100: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6110: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6120: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
6130: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6140: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6150: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6160: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
6170: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6180: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61a0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
61b0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
61c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
61d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61e0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
61f0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
6200: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6210: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6220: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
6230: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
6240: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6250: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6260: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6270: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6280: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62a0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
62b0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
62c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
62d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62e0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
62f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6300: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6310: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6330: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
6340: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6350: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6360: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6380: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6390: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
63a0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
63b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63d0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
63e0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
63f0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6400: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6410: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6420: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
6430: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
6440: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6450: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6470: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6480: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6490: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
64a0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
64b0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
64c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
64d0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
64e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
64f0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6500: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6510: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
6520: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
6530: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
6540: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6550: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6560: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6570: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6580: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6590: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
65a0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
65b0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
65c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
65d0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
65e0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
65f0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6600: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6610: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6620: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6630: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6640: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6650: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6660: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6670: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6680: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6690: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
66a0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
66b0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
66c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66d0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
66e0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
66f0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6700: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6710: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6720: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6730: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6740: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6750: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6760: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6770: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6780: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6790: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
67a0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
67b0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
67c0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
67d0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
67e0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
67f0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6800: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6810: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6820: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6830: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6840: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6850: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6860: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6870: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6880: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6890: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
68a0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
68b0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
68c0: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
68d0: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
68e0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
68f0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6900: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6910: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6920: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6930: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6940: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6950: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
6960: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6970: 77 68 65 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23 64  when open..*/.#d
6980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6990: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
69a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69b0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
69c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69d0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
69e0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
69f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a00: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6a10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a20: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6a30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a50: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6a60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a70: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6a80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6aa0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6ab0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ac0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
6ad0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ae0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6af0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b10: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6b20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b30: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6b40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b50: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6b60: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b80: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6b90: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ba0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6bb0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6bc0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
6bd0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
6be0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bf0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6c00: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6c10: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c20: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6c30: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6c40: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
6c50: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6c60: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6c70: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6c80: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6c90: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6ca0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6cb0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6cc0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6cd0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6ce0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6cf0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6d00: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6d10: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6d20: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6d30: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6d40: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6d50: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6d70: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6d80: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6d90: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6da0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6db0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6dc0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6dd0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6de0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6df0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6e00: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6e10: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6e20: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6e30: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6e40: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6e50: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6e60: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6e70: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6e80: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6e90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6ea0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6eb0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6ec0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6ed0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6ee0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6ef0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6f00: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6f10: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6f20: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6f30: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6f40: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6f50: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6f60: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6f70: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6f80: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6f90: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6fa0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6fb0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6fc0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6fd0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6fe0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6ff0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7000: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7010: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7020: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7030: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7040: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7050: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7060: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7070: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7080: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7090: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
70a0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
70b0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
70c0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
70d0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
70e0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
70f0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
7100: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7110: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7120: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7130: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7140: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7150: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7160: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7170: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7180: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7190: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
71a0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
71b0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
71c0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
71d0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
71e0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
71f0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
7200: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7210: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7220: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7230: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7240: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7250: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7260: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7270: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7280: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7290: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
72a0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
72b0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
72c0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
72d0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
72e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72f0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7300: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7310: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7320: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7330: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7340: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7350: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7360: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7370: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7380: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7390: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
73a0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
73b0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
73c0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
73d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
73e0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
73f0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7400: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7410: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7420: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7430: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7440: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7450: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7460: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7470: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7480: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7490: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
74a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
74b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
74c0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
74d0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
74e0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
74f0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7500: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7510: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7520: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7530: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7540: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7550: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7560: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7570: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7580: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7590: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
75a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
75b0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
75c0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
75d0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
75e0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
75f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7600: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7610: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7620: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7630: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7640: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7650: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7660: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7670: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7680: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7690: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
76a0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
76b0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
76c0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
76d0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
76e0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
76f0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7700: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7710: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7720: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7730: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7740: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7750: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7760: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7770: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7780: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7790: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
77a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
77b0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
77c0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
77d0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
77e0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
77f0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7800: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7810: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7820: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7830: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7840: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7850: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7860: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7870: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7880: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7890: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
78a0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
78b0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
78c0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
78d0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
78e0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
78f0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7900: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7910: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7920: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7930: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7940: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7950: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7960: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7970: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7980: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7990: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
79a0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
79b0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
79c0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
79d0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
79e0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
79f0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7a00: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7a10: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7a20: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7a30: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7a40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7a50: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7a60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7a70: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7a80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7a90: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7ab0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7ac0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7ad0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
7ae0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7af0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7b00: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7b10: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7b20: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7b30: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7b40: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7b50: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7b60: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7b70: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7b80: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
7b90: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7ba0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7bb0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7bc0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
7bd0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
7be0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7bf0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7c00: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7c10: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7c20: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7c30: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7c40: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7c50: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7c60: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7c70: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7c80: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7c90: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7ca0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7cb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7cc0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7cd0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7ce0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7cf0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7d00: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7d10: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7d20: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7d30: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7d40: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7d50: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7d60: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7d70: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7d80: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7d90: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7da0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7db0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7dc0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7dd0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7de0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7df0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7e00: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7e10: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7e20: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7e30: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7e40: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7e50: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7e60: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7e70: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7e80: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7e90: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7ea0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7eb0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7ec0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7ed0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7ee0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7ef0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7f00: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7f10: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7f20: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7f30: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7f40: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7f50: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7f60: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7f70: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7f80: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7f90: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7fa0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7fb0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7fc0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7fd0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7fe0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7ff0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
8000: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8010: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8020: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8030: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8040: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8050: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8060: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8070: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8080: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
8090: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
80a0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
80b0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
80c0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
80d0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
80e0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
80f0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
8100: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8110: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8120: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8130: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8140: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8160: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8170: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8180: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
8190: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81a0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
81b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81c0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
81d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81e0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
81f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8200: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8210: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8220: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8230: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8240: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8250: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8260: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8270: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8280: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
8290: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82a0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
82b0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
82c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
82d0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
82e0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
82f0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
8300: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8310: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8320: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8330: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8340: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8350: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8360: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8370: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8380: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8390: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
83a0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
83b0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
83c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
83d0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
83e0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
83f0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8400: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8410: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8420: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8430: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8440: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8450: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8460: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8470: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8480: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8490: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
84a0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
84b0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
84c0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
84d0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
84e0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
84f0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8500: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8510: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8520: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8530: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8540: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8550: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8560: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8570: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8580: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8590: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
85a0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
85b0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
85c0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
85d0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
85e0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
85f0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8600: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8610: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8620: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8630: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8640: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8650: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8660: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8670: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8680: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8690: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
86a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
86b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
86c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
86d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
86e0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
86f0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8700: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8710: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8720: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8730: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8740: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8750: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8760: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8770: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8780: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8790: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
87a0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
87b0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
87c0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
87d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
87e0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8800: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8810: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8820: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8830: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8840: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8850: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8860: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8870: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8880: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8890: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88a0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
88b0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
88c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88d0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
88e0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
88f0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8900: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8910: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8920: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8930: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8940: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8950: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8960: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8970: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8980: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8990: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
89a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
89b0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
89c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
89d0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
89e0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
89f0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8a00: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8a10: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8a20: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8a30: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8a40: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8a50: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8a60: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8a70: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8a80: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8a90: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8aa0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8ab0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8ac0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
8ad0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
8ae0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8af0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8b00: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8b10: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8b20: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8b30: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
8b40: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8b50: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8b60: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8b80: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8b90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8ba0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8bb0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8bc0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8bd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
8be0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8bf0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8c00: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8c10: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8c20: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8c30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8c40: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8c50: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8c60: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8c70: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8c80: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8c90: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8ca0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8cb0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8cc0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8cd0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8ce0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8cf0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8d00: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8d10: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8d20: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8d30: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8d40: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8d50: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8d60: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8d70: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8d80: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8d90: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8da0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8db0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8dc0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8dd0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8de0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8df0: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8e00: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8e10: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8e20: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8e30: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8e40: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8e50: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8e60: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8e70: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8e80: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8e90: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8ea0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8eb0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8ec0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8ed0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8ee0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8ef0: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8f00: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8f10: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8f20: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8f30: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8f40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8f50: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8f60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8f70: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8f80: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8f90: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8fa0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8fb0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8fc0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8fd0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
8fe0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
8ff0: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
9000: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
9010: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
9020: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9030: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
9040: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
9050: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
9060: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
9070: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
9080: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
9090: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
90a0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
90b0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
90c0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
90d0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
90e0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
90f0: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
9100: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
9110: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
9120: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
9130: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
9140: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9150: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
9160: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9170: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9180: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9190: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
91a0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
91b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
91c0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
91d0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
91e0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
91f0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
9200: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9210: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
9220: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
9230: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
9240: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
9250: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9260: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
9270: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
9280: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
9290: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
92a0: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
92b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
92c0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
92d0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
92e0: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
92f0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9300: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9310: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9320: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9330: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
9340: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
9350: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
9360: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
9370: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
9380: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
9390: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
93a0: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
93b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
93c0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
93d0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
93e0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
93f0: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9400: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9410: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9420: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9430: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
9440: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9450: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
9460: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
9470: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
9480: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
9490: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
94a0: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
94b0: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
94c0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
94d0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
94e0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
94f0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9500: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9510: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9520: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9530: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
9540: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9550: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9560: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
9570: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
9580: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
9590: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
95a0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
95b0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
95c0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
95d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
95e0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
95f0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9600: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9610: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9620: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9630: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9640: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9650: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
9660: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9670: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
9680: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
9690: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
96a0: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
96b0: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
96c0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
96d0: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
96e0: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
96f0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9700: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9710: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9720: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9730: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9740: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
9750: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
9760: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9770: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9780: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9790: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
97a0: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
97b0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
97c0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
97d0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
97e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
97f0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9800: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9810: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9820: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9830: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9840: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9850: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9860: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9870: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9880: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
9890: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
98a0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
98b0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
98c0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
98d0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
98e0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
98f0: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9900: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
9910: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
9920: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
9930: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
9940: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
9950: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9960: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
9970: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
9980: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
9990: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
99a0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
99b0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
99c0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
99d0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
99e0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
99f0: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
9a00: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
9a10: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
9a20: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
9a30: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
9a40: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
9a50: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9a60: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9a70: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9a80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9a90: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9aa0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9ab0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9ac0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9ad0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9ae0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9af0: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
9b00: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
9b10: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
9b20: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
9b30: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
9b40: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
9b50: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9b60: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9b70: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9b80: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9b90: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9ba0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9bb0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9bc0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9bd0: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9be0: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9bf0: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
9c00: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
9c10: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
9c20: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
9c30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c40: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9c50: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9c60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9c70: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9c80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9c90: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9ca0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9cb0: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9cc0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9cd0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9ce0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9cf0: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
9d00: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d10: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
9d20: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
9d30: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
9d40: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
9d50: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9d60: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9d70: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9d80: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9d90: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9da0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
9db0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
9dc0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
9dd0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
9de0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
9df0: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
9e00: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
9e10: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
9e20: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
9e30: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
9e40: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
9e50: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
9e60: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
9e70: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
9e80: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
9e90: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
9ea0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
9eb0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
9ec0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
9ed0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
9ee0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
9ef0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9f00: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
9f10: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
9f20: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
9f30: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
9f40: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
9f50: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
9f60: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9f70: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
9f80: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
9f90: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9fa0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9fb0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9fc0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9fd0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9fe0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
9ff0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a010: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a020: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a030: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a040: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a050: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a060: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a070: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a080: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a090: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a0a0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a0b0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a0c0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a0d0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a0e0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a0f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a100: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a110: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a120: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a130: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a140: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a150: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a160: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a170: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a180: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a190: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a1a0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a1b0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a1c0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a1d0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a1e0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a1f0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a200: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a210: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a220: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a230: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a240: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a250: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a260: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a270: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a280: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a290: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a2a0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a2b0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a2c0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a2d0: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a2e0: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a2f0: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a300: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a310: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
a320: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
a330: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
a340: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
a350: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a360: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a370: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a380: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a390: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3a0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a3b0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a3c0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a3d0: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a3e0: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a3f0: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a400: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a410: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a420: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a430: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a440: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a450: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a460: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a470: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a480: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a490: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a4a0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a4b0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a4c0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a4d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a4e0: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a4f0: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a500: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a510: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a520: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a530: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a540: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a550: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a560: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a570: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a580: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a590: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a5a0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a5b0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a5c0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a5d0: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a5e0: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a5f0: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a600: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a610: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a620: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a630: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a640: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a650: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
a660: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
a670: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
a680: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
a690: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
a6a0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a6b0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
a6c0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
a6d0: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
a6e0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
a6f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a700: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
a710: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
a720: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
a730: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
a740: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a750: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a760: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
a770: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
a780: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
a790: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
a7a0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
a7b0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
a7c0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
a7d0: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
a7e0: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
a7f0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
a800: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
a810: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
a820: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
a830: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
a840: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
a850: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a860: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
a870: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
a880: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
a890: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
a8a0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
a8b0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
a8c0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
a8d0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
a8e0: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
a8f0: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
a900: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
a910: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
a920: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
a930: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
a940: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
a950: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
a960: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
a970: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a980: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a990: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a9a0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
a9b0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
a9c0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
a9d0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a9e0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a9f0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa00: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
aa10: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
aa20: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
aa30: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
aa40: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
aa50: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
aa60: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
aa70: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
aa80: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
aa90: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
aaa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aab0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
aac0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
aad0: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
aae0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
aaf0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
ab00: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
ab10: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
ab20: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
ab30: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
ab40: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
ab50: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
ab60: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
ab70: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
ab80: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
ab90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
aba0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
abb0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
abc0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
abd0: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
abe0: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
abf0: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
ac00: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
ac10: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
ac20: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
ac30: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ac40: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ac50: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
ac60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ac70: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
ac80: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
ac90: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
aca0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
acb0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
acc0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
acd0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
ace0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
acf0: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
ad00: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
ad10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
ad20: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
ad30: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
ad40: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
ad50: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
ad60: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
ad70: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
ad80: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
ad90: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
ada0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
adb0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
adc0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
add0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
ade0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
adf0: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
ae00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
ae10: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
ae20: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
ae30: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
ae40: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
ae50: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
ae60: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
ae70: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
ae80: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
ae90: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
aea0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
aeb0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
aec0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
aed0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
aee0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
aef0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
af00: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
af10: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
af20: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
af30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af40: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
af50: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
af60: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
af70: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
af80: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
af90: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
afa0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
afb0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
afc0: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
afd0: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
afe0: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
aff0: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b000: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b010: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b020: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b030: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b040: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b050: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b060: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b070: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b080: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b090: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b0a0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b0b0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b0c0: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b0d0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b0e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b0f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b100: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b110: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b120: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b130: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b140: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b150: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b160: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b170: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b180: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b190: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b1a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b1b0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b1c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b1d0: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b1e0: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b1f0: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b200: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b210: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b220: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b230: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b240: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b250: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b260: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b270: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b280: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b290: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b2a0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b2b0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b2c0: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b2d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b2e0: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b2f0: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b300: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b310: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b320: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b330: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b340: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b350: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b360: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b370: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b380: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b390: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b3a0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b3b0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b3c0: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b3d0: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b3e0: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b3f0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b400: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b410: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b420: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b430: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b440: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b450: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b460: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b470: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b480: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b490: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b4a0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b4b0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
b4c0: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
b4d0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
b4e0: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
b4f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b500: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b510: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
b520: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b530: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
b540: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
b550: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
b560: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
b570: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
b580: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
b590: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
b5a0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
b5b0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
b5c0: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
b5d0: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
b5e0: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
b5f0: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
b600: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
b610: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
b620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b630: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
b640: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
b650: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
b660: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b670: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
b680: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
b690: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b6a0: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
b6b0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
b6c0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
b6d0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
b6e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
b6f0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
b700: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
b710: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b720: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
b730: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
b740: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b750: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
b760: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
b770: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
b780: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
b790: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
b7a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b7b0: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
b7c0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
b7d0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
b7e0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
b7f0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
b800: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
b810: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b820: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b830: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
b840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
b850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b860: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
b870: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
b880: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b890: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
b8a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
b8b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b8c0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
b8d0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
b8e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8f0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
b900: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
b910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b920: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
b930: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
b940: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b950: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
b960: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
b970: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b980: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
b990: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
b9a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
b9b0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
b9c0: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
b9d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
b9e0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
b9f0: 20 20 20 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20 43       22../*.** C
ba00: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
ba10: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
ba20: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
ba30: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
ba40: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
ba50: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
ba60: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
ba70: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
ba80: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
ba90: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
baa0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
bab0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
bac0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
bad0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
bae0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
baf0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
bb00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
bb10: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
bb20: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
bb30: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
bb40: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
bb50: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
bb60: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
bb70: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
bb80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
bb90: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
bba0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
bbb0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
bbc0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
bbd0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
bbe0: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
bbf0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
bc00: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
bc10: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
bc20: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
bc30: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
bc40: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
bc50: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
bc60: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
bc70: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
bc80: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
bc90: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
bca0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
bcb0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
bcc0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
bcd0: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
bce0: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
bcf0: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
bd00: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
bd10: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
bd20: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
bd30: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
bd40: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
bd50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
bd60: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
bd70: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
bd80: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
bd90: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
bda0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
bdb0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
bdc0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
bdd0: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
bde0: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
bdf0: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
be00: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
be10: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
be20: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
be30: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
be40: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
be50: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
be60: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
be70: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
be80: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
be90: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
bea0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
beb0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
bec0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
bed0: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
bee0: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
bef0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
bf00: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
bf10: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
bf20: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
bf30: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
bf40: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
bf50: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
bf60: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
bf70: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
bf80: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
bf90: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
bfa0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
bfb0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
bfc0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
bfd0: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
bfe0: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
bff0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
c000: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
c010: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
c020: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
c030: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
c040: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
c050: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
c060: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
c070: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c080: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
c090: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
c0a0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
c0b0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
c0c0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
c0d0: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
c0e0: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
c0f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c100: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
c110: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
c120: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c130: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
c140: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
c150: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
c160: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
c170: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
c180: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
c190: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
c1a0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
c1b0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
c1c0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
c1d0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
c1e0: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
c1f0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
c200: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
c210: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c220: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
c230: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
c240: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
c250: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
c260: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
c270: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
c280: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
c290: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
c2a0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
c2b0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
c2c0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
c2d0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
c2e0: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
c2f0: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
c300: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
c310: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
c320: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
c330: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
c340: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c350: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
c360: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
c370: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
c380: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
c390: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
c3a0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
c3b0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
c3c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c3d0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
c3e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
c3f0: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
c400: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
c410: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
c420: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
c430: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
c440: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c450: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
c460: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
c470: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
c480: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
c490: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
c4a0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
c4b0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
c4c0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c4d0: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
c4e0: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
c4f0: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
c500: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
c510: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
c520: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c530: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
c540: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
c550: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
c560: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
c570: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
c580: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c590: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
c5a0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
c5b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
c5c0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
c5d0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
c5e0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
c5f0: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
c600: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
c610: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
c620: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
c630: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
c640: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
c650: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
c660: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
c670: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
c680: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
c690: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
c6a0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
c6b0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
c6c0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
c6d0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
c6e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
c6f0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
c700: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
c710: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
c720: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
c730: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
c740: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c750: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
c760: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
c770: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
c780: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c790: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
c7a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c7b0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
c7c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c7d0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
c7e0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c7f0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
c800: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
c820: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
c830: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c840: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
c850: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
c860: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
c870: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
c880: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
c890: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
c8a0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
c8b0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
c8c0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
c8d0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
c8e0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
c8f0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
c900: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
c910: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
c920: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
c930: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
c940: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
c950: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
c960: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
c970: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
c980: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
c990: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
c9a0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
c9b0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
c9c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
c9d0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
c9e0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
c9f0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
ca00: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
ca10: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
ca20: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
ca30: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
ca40: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
ca50: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
ca60: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
ca70: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
ca80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
ca90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
caa0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
cab0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
cac0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
cad0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
cae0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
caf0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
cb00: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
cb10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
cb20: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
cb30: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
cb40: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
cb50: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
cb60: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
cb70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
cb80: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
cb90: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
cba0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
cbb0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
cbc0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
cbd0: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
cbe0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
cbf0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
cc00: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
cc10: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
cc20: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
cc30: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
cc40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
cc50: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
cc60: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
cc70: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
cc80: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
cc90: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
cca0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
ccb0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
ccc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
ccd0: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
cce0: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
ccf0: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
cd00: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
cd10: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
cd20: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
cd30: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
cd40: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
cd50: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
cd60: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
cd70: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
cd80: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
cd90: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
cda0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
cdb0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
cdc0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
cdd0: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
cde0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
cdf0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
ce00: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
ce10: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
ce20: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
ce30: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
ce40: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
ce50: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
ce60: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
ce70: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
ce80: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
ce90: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
cea0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
ceb0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
cec0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
ced0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
cee0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
cef0: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
cf00: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
cf10: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
cf20: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
cf30: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
cf40: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
cf50: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
cf60: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
cf70: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
cf80: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
cf90: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
cfa0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
cfb0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
cfc0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
cfd0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
cfe0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
cff0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
d000: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
d010: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
d020: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d030: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
d040: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
d050: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
d060: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
d070: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
d080: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
d090: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d0a0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
d0b0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
d0c0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
d0d0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
d0e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
d0f0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
d100: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
d110: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
d120: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
d130: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
d140: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
d150: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
d160: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
d170: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
d180: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
d190: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
d1a0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
d1b0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
d1c0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d1d0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
d1e0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
d1f0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
d200: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d210: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
d220: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
d230: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
d240: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
d250: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
d260: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
d270: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
d280: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
d290: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
d2a0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
d2b0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
d2c0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
d2d0: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
d2e0: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
d2f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
d300: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
d310: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
d320: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
d330: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
d340: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d350: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
d360: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
d370: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
d380: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
d390: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
d3a0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
d3b0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
d3c0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
d3d0: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
d3e0: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
d3f0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
d400: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
d410: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
d420: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
d430: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
d440: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
d450: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
d460: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
d470: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
d480: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
d490: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
d4a0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
d4b0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
d4c0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
d4d0: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
d4e0: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
d4f0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
d500: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
d510: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
d520: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
d530: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
d540: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
d550: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
d560: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
d570: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
d580: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
d590: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
d5a0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
d5b0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
d5c0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
d5d0: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
d5e0: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
d5f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
d600: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
d610: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
d620: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
d630: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
d640: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
d650: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
d660: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
d670: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
d680: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
d690: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
d6a0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
d6b0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
d6c0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
d6d0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d6e0: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
d6f0: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
d700: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
d710: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
d720: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
d730: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
d740: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
d750: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
d760: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
d770: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
d780: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
d790: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
d7a0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
d7b0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
d7c0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
d7d0: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
d7e0: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
d7f0: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
d800: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
d810: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
d820: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
d830: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
d840: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
d850: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
d860: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
d870: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
d880: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
d890: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
d8a0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
d8b0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
d8c0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
d8d0: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
d8e0: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
d8f0: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
d900: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
d910: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
d920: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
d930: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
d940: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
d950: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
d960: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
d970: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
d980: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
d990: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
d9a0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
d9b0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
d9c0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
d9d0: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
d9e0: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
d9f0: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
da00: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
da10: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
da20: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
da30: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
da40: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
da50: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
da60: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
da70: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
da80: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
da90: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
daa0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
dab0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
dac0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
dad0: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
dae0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
daf0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
db00: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
db10: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
db20: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
db30: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
db40: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
db50: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
db60: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
db70: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
db80: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
db90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
dba0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
dbb0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
dbc0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
dbd0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
dbe0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
dbf0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
dc00: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
dc10: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
dc20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
dc30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
dc40: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
dc50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
dc60: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
dc70: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
dc80: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
dc90: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
dca0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
dcb0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
dcc0: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
dcd0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
dce0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
dcf0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
dd00: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
dd10: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
dd20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dd30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
dd40: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
dd50: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
dd60: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
dd70: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dd80: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
dd90: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
dda0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ddb0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
ddc0: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
ddd0: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
dde0: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
ddf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
de00: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
de10: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
de20: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
de30: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
de40: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
de50: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
de60: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
de70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
de80: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
de90: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
dea0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
deb0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
dec0: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
ded0: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
dee0: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
def0: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
df00: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
df10: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
df20: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
df30: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
df40: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
df50: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
df60: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
df70: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
df80: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
df90: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
dfa0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
dfb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
dfc0: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
dfd0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
dfe0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
dff0: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
e000: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
e010: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e020: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
e030: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
e040: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
e050: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
e060: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e070: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e080: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e090: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
e0a0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
e0b0: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
e0c0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e0d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e0e0: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
e0f0: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
e100: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e110: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e120: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
e130: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e140: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e150: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
e160: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
e170: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
e180: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
e190: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
e1a0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
e1b0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
e1c0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
e1d0: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
e1e0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
e1f0: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
e200: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
e210: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
e220: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
e230: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e240: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
e250: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
e260: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
e270: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
e280: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
e290: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
e2a0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
e2b0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
e2c0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
e2d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e2e0: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
e2f0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
e300: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
e310: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e320: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
e330: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e340: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
e350: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
e360: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
e370: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e380: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
e390: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
e3a0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
e3b0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
e3c0: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
e3d0: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
e3e0: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
e3f0: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
e400: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
e410: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
e420: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
e430: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
e440: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
e450: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
e460: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
e470: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
e480: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
e490: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
e4a0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
e4b0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
e4c0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
e4d0: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
e4e0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e4f0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
e500: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
e510: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
e520: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e530: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
e540: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
e550: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
e560: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
e570: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
e580: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
e590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
e5a0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
e5b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e5c0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
e5d0: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
e5e0: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
e5f0: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
e600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
e610: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
e620: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
e630: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e640: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
e650: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
e660: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
e670: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
e680: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
e690: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
e6a0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
e6b0: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
e6c0: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
e6d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
e6e0: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
e6f0: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
e700: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
e710: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
e720: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
e730: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
e740: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
e750: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
e760: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
e770: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
e780: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
e790: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
e7a0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
e7b0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
e7c0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
e7d0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e7e0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
e7f0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
e800: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
e810: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
e820: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
e830: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
e840: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
e850: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
e860: 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73  en no the corres
e870: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
e880: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
e890: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
e8a0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e8b0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
e8c0: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
e8d0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
e8e0: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
e8f0: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
e900: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
e910: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
e920: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
e930: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
e940: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
e950: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
e960: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
e970: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
e980: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
e990: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
e9a0: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
e9b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
e9c0: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
e9d0: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
e9e0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
e9f0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
ea00: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
ea10: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
ea20: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
ea30: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
ea40: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
ea50: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
ea60: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
ea70: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
ea80: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
ea90: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
eaa0: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
eab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
eac0: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
ead0: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
eae0: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
eaf0: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
eb00: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
eb10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eb20: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
eb30: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
eb40: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
eb50: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
eb60: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
eb70: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
eb80: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
eb90: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
eba0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
ebb0: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
ebc0: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
ebd0: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
ebe0: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
ebf0: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
ec00: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
ec10: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
ec20: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
ec30: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
ec40: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
ec50: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
ec60: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
ec70: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
ec80: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
ec90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eca0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
ecb0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
ecc0: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
ecd0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
ece0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ecf0: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
ed00: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
ed10: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
ed20: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
ed30: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
ed40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
ed50: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
ed60: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
ed70: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ed80: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
ed90: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
eda0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
edb0: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
edc0: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
edd0: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
ede0: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
edf0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
ee00: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
ee10: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ee20: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
ee30: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
ee40: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
ee50: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ee60: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
ee70: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
ee80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
ee90: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
eea0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
eeb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eec0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
eed0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
eee0: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
eef0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
ef00: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
ef10: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
ef20: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
ef30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ef40: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
ef50: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
ef60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef70: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
ef80: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ef90: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
efa0: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
efb0: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
efc0: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
efd0: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
efe0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
eff0: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
f000: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
f010: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
f020: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
f030: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
f040: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
f050: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
f060: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
f070: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
f080: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
f090: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f0a0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
f0b0: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
f0c0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
f0d0: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
f0e0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
f0f0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f100: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f110: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
f120: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f130: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
f140: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
f150: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f160: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
f170: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
f180: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
f190: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
f1a0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
f1b0: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
f1c0: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
f1d0: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
f1e0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
f1f0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
f200: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
f210: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f220: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
f230: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
f240: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
f250: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
f260: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
f270: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
f280: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
f290: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
f2a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f2b0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
f2c0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
f2d0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
f2e0: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
f2f0: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
f300: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
f310: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
f320: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
f330: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
f340: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
f350: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
f360: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
f370: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
f380: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
f390: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f3a0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
f3b0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
f3c0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
f3d0: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
f3e0: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
f3f0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
f400: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
f410: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
f420: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
f430: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
f440: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
f450: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
f460: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
f470: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
f480: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
f490: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
f4a0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
f4b0: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
f4c0: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
f4d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f4e0: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
f4f0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
f500: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
f510: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
f520: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
f530: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
f540: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
f550: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
f560: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
f570: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
f580: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f590: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
f5a0: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
f5b0: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
f5c0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
f5d0: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
f5e0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
f5f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
f600: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
f610: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
f620: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
f630: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
f640: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
f650: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
f660: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
f670: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
f680: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
f690: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
f6a0: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
f6b0: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
f6c0: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
f6d0: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
f6e0: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
f6f0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
f700: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
f710: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f720: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
f730: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
f740: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
f750: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
f760: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
f770: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
f780: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
f790: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f7a0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
f7b0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
f7c0: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
f7d0: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
f7e0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
f7f0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
f800: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
f810: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
f820: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
f830: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f840: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
f850: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
f860: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
f870: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
f880: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
f890: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
f8a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f8b0: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
f8c0: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
f8d0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
f8e0: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
f8f0: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
f900: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
f910: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f920: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
f930: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
f940: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
f950: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
f960: 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
f970: 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
f980: 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
f990: 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
f9a0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
f9b0: 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
f9c0: 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
f9d0: 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
f9e0: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
f9f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
fa00: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
fa10: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
fa20: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
fa30: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
fa40: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
fa50: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
fa60: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
fa70: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
fa80: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fa90: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
faa0: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
fab0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
fac0: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
fad0: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
fae0: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
faf0: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
fb00: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
fb10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
fb20: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
fb30: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
fb40: 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  own(void);.SQLIT
fb50: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
fb60: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
fb70: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
fb80: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
fb90: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
fba0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
fbb0: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
fbc0: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
fbd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fbe0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
fbf0: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
fc00: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
fc10: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
fc20: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
fc30: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
fc40: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
fc50: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
fc60: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
fc70: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
fc80: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
fc90: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
fca0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
fcb0: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
fcc0: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
fcd0: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
fce0: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
fcf0: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
fd00: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
fd10: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
fd20: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
fd30: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
fd40: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
fd50: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
fd60: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
fd70: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
fd80: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
fd90: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
fda0: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
fdb0: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
fdc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
fdd0: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
fde0: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
fdf0: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
fe00: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
fe10: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
fe20: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fe30: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
fe40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
fe50: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
fe60: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
fe70: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
fe80: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
fe90: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
fea0: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
feb0: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
fec0: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
fed0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
fee0: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
fef0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
ff00: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
ff10: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
ff20: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
ff30: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
ff40: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
ff50: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
ff60: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
ff70: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
ff80: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
ff90: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ffa0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
ffb0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
ffc0: 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
ffd0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
ffe0: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
fff0: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
10000 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
10010 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
10020 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10030 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
10040 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
10050 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10060 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10070 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
10080 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
10090 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
100a0 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
100b0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
100c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
100d0 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
100e0 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
100f0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
10100 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
10110 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
10120 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
10130 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10140 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ode]..*/.SQLITE_
10150 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
10160 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
10170 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10180 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
10190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
101a0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
101b0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
101c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
101d0 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
101e0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
101f0 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
10200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
10210 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
10220 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
10230 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10240 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
10250 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
10260 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
10270 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10280 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
10290 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
102a0 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
102b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
102c0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
102d0 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
102e0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
102f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
10300 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
10310 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
10320 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
10330 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
10340 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
10350 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
10360 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
10370 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
10380 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
10390 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
103a0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
103b0 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
103c0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
103d0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
103e0 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
103f0 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
10400 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
10410 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
10420 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51  uccessful..*/.SQ
10430 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
10440 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
10450 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
10460 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10470 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
10480 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
10490 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
104a0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
104b0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
104c0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
104d0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
104e0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
104f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10500 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
10510 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
10520 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
10530 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
10540 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
10550 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
10560 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10570 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
10580 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
10590 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
105a0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
105b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
105c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
105d0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
105e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
105f0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10600 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
10610 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10620 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
10630 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
10640 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
10650 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10660 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
10670 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
10680 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
10690 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
106a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
106b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
106c0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
106d0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
106e0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
106f0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10700 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10710 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10720 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10730 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10740 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
10750 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
10760 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
10770 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
10780 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10790 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
107a0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
107b0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
107c0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
107d0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
107e0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
107f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10800 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10810 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10820 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10830 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10840 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10850 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
10860 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10870 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
10880 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
10890 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
108a0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
108b0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
108c0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
108d0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
108e0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
108f0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10900 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10910 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10920 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10930 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10940 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
10950 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
10960 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
10970 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10980 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
10990 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
109a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
109b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
109c0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
109d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
109e0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
109f0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10a00 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10a10 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10a20 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
10a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10a40 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
10a50 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
10a60 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
10a70 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
10a80 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
10a90 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
10aa0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
10ab0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
10ac0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
10ad0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
10ae0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
10af0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
10b00 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
10b10 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
10b20 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
10b30 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
10b40 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
10b50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
10b60 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
10b70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10b80 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
10b90 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
10ba0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
10bb0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10bc0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
10bd0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
10be0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
10bf0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
10c00 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
10c10 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
10c20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10c30 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
10c40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
10c50 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
10c60 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
10c70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
10c80 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
10c90 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
10ca0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10cb0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
10cc0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10cd0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
10ce0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10cf0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
10d00 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
10d10 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
10d20 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
10d30 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
10d40 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
10d50 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
10d60 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
10d70 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
10d80 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
10d90 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
10da0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
10db0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
10dc0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
10dd0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
10de0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
10df0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
10e00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
10e10 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
10e20 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
10e30 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
10e40 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
10e50 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
10e60 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
10e70 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
10e80 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
10e90 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
10ea0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
10eb0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
10ec0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
10ed0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
10ee0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ef0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
10f00 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
10f10 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
10f20 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
10f30 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
10f40 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
10f50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
10f60 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
10f70 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
10f80 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10f90 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
10fa0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10fb0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
10fc0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
10fd0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
10fe0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
10ff0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
11000 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
11010 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
11020 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11030 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11040 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11050 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11060 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11070 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
11080 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
11090 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
110a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
110b0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
110c0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
110d0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
110e0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
110f0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
11100 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
11110 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
11120 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11130 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
11140 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
11150 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11160 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
11170 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
11180 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
11190 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
111a0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
111b0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
111c0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
111d0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
111e0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
111f0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
11200 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
11210 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11220 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
11230 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11240 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
11250 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
11260 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11270 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
11280 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
11290 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
112a0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
112b0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
112c0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
112d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
112e0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
112f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11300 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
11310 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
11320 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
11330 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11340 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11350 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
11360 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
11370 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
11380 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
11390 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
113a0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
113b0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
113c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
113d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
113e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
113f0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
11400 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
11410 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
11420 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
11430 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
11440 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11450 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
11460 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11470 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
11480 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
11490 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
114a0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
114b0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
114c0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
114d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
114e0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
114f0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11500 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
11510 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
11520 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
11530 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11540 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11550 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11560 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
11570 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11580 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
11590 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
115a0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
115b0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
115c0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
115d0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
115e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
115f0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11600 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
11610 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11620 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11630 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11640 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11650 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11660 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11670 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11680 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11690 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
116a0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
116b0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
116c0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
116d0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
116e0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
116f0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
11700 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
11710 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
11720 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
11730 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11740 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11750 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11760 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11770 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11780 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11790 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
117a0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
117b0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
117c0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
117d0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
117e0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
117f0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
11800 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11810 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
11820 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11830 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11840 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11850 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
11860 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11870 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11880 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11890 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
118a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
118b0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
118c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
118d0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
118e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
118f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11900 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11910 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
11920 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
11930 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11940 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
11950 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
11960 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11970 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11980 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11990 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
119a0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
119b0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
119c0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
119d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
119e0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
119f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
11a00 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
11a10 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
11a20 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
11a30 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
11a40 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
11a50 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
11a60 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
11a70 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
11a80 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
11a90 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
11aa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11ab0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
11ac0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
11ad0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11ae0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11af0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11b00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11b10 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11b20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11b30 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11b40 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
11b50 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
11b60 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11b70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11b80 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11b90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11ba0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11bb0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11bc0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
11bd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11be0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11bf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11c00 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
11c10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11c20 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
11c30 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11c40 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11c50 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11c60 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11c70 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11c80 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
11c90 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
11ca0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
11cb0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
11cc0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
11cd0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
11ce0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
11cf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11d00 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
11d10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11d20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
11d30 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
11d40 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
11d50 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
11d60 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
11d70 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11d80 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
11d90 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
11da0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
11db0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
11dc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11dd0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
11de0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
11df0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
11e00 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
11e10 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
11e20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11e30 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
11e40 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
11e50 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
11e60 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
11e70 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
11e80 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
11e90 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11ea0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11eb0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11ec0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11ed0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11ee0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11ef0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11f00 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
11f10 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
11f20 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
11f30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11f40 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
11f50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
11f60 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
11f70 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
11f80 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
11f90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11fa0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11fc0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
11fd0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
11fe0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
11ff0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12000 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12010 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
12020 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
12030 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12040 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12050 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
12060 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12070 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12080 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
120a0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
120b0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
120c0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
120d0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
120e0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
120f0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
12100 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
12110 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
12120 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
12130 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12140 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12150 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
12160 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12170 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
12180 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
121a0 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
121b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
121c0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
121d0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
121e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
121f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12200 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12210 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12220 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12230 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12240 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
12250 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12260 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
12270 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12280 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12290 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
122a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
122b0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
122c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
122d0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
122e0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
122f0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
12300 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
12310 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
12320 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
12330 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
12340 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
12350 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
12360 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
12370 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12380 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
12390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
123a0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
123b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
123c0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
123d0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
123e0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
123f0 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
12400 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
12410 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
12420 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
12430 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12440 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
12450 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
12460 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12470 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12480 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
12490 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
124a0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
124b0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
124c0 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
124d0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
124e0 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
124f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12500 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12510 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12520 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
12530 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
12540 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
12550 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
12560 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
12570 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12580 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
12590 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
125a0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
125b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
125c0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
125d0 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
125e0 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
125f0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
12600 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12610 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12620 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12630 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12640 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
12650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12660 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
12670 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
12680 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12690 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
126a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
126b0 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
126c0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
126d0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
126e0 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
126f0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
12700 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
12710 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
12720 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
12730 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
12740 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
12750 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
12760 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
12770 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
12780 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
12790 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
127a0 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
127b0 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
127c0 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
127d0 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
127e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
127f0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
12800 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
12810 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
12820 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
12830 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
12840 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12850 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
12860 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
12870 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
12880 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
12890 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
128a0 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
128b0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
128c0 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
128d0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
128e0 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
128f0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
12900 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
12910 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
12920 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
12930 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
12940 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
12950 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12960 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
12970 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
12980 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
12990 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
129a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
129b0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
129c0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
129d0 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
129e0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
129f0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12a00 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
12a10 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12a20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12a30 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
12a40 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
12a50 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
12a60 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
12a70 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
12a80 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
12a90 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
12aa0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
12ab0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
12ac0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
12ad0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
12ae0 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
12af0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
12b00 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
12b10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
12b20 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
12b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12b40 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
12b50 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
12b60 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12b70 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
12b80 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
12b90 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
12ba0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
12bb0 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
12bc0 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
12bd0 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
12be0 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
12bf0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
12c00 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
12c10 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
12c20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
12c30 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
12c40 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
12c50 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
12c60 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
12c70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
12c80 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
12c90 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
12ca0 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
12cb0 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
12cc0 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
12cd0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
12ce0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
12cf0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
12d00 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
12d10 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
12d20 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
12d30 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
12d40 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
12d50 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
12d60 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
12d70 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
12d80 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
12d90 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
12da0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12db0 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
12dc0 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
12dd0 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
12de0 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
12df0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
12e00 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
12e10 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
12e20 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
12e30 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
12e40 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
12e50 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
12e60 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
12e70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12e80 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
12e90 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
12ea0 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
12eb0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12ec0 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
12ed0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
12ee0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
12ef0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
12f00 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
12f10 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
12f20 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
12f30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12f40 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
12f50 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
12f60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12f70 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
12f80 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12f90 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
12fa0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
12fb0 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
12fc0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
12fd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12fe0 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
12ff0 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
13000 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
13010 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13030 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
13040 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13050 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
13060 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
13070 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
13080 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
13090 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
130a0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
130b0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
130c0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
130d0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
130e0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
130f0 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
13100 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
13110 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
13120 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
13130 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13140 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
13150 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
13160 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
13170 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
13180 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
13190 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
131a0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
131b0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
131c0 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
131d0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
131e0 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
131f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
13200 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
13210 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
13220 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13230 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13240 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13250 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
13260 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
13270 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
13280 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
13290 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
132a0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
132b0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
132c0 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
132d0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
132e0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
132f0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13300 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13310 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13320 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13330 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13340 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13350 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13360 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
13370 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
13380 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
13390 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
133a0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
133b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
133c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
133d0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
133e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
133f0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13400 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
13410 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13420 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13430 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13440 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
13450 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
13460 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
13470 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
13480 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
13490 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
134a0 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
134b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
134c0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
134d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
134e0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
134f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13500 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13510 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
13520 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13530 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
13540 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
13550 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13560 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13570 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13580 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13590 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
135a0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
135b0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
135c0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
135d0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
135e0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
135f0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
13600 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13610 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13620 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
13630 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
13640 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
13650 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
13660 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13670 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13680 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13690 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
136a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
136b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
136c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
136d0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
136e0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
136f0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13700 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13710 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13720 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
13730 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13740 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13750 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13760 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13770 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
13780 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
13790 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
137a0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
137b0 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
137c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
137d0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
137e0 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
137f0 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
13800 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
13810 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
13820 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
13830 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
13840 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13850 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13860 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13870 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13880 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13890 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
138a0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
138b0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
138c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
138d0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
138e0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
138f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13900 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13910 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
13920 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13930 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13940 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13950 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13970 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
13980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13990 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
139a0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
139b0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
139c0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
139d0 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
139e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
139f0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
13a00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
13a10 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
13a20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13a30 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
13a40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
13a50 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
13a60 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
13a70 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
13a80 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
13a90 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
13aa0 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
13ab0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
13ac0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
13ad0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
13ae0 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
13af0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
13b00 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
13b10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13b20 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
13b30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13b40 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
13b50 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
13b60 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
13b70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
13b80 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
13b90 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
13ba0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13bb0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
13bc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13bd0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
13be0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
13bf0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13c00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13c10 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
13c20 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
13c30 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
13c40 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
13c50 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
13c60 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
13c70 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
13c80 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13c90 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
13ca0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13cb0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
13cc0 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
13cd0 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
13ce0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13cf0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
13d00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13d10 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
13d20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13d30 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13d40 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13d50 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13d60 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13d70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13d80 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
13d90 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13da0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
13db0 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
13dc0 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
13dd0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13de0 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
13df0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
13e00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13e10 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
13e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
13e30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
13e40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13e50 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
13e60 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
13e70 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
13e80 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
13e90 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
13ea0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
13eb0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
13ec0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
13ed0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
13ee0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
13ef0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
13f00 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
13f10 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
13f20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
13f30 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
13f40 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
13f50 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
13f60 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
13f70 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13f80 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
13f90 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
13fa0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
13fb0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
13fc0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
13fd0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
13fe0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
13ff0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
14000 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
14010 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14020 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
14030 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
14040 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
14050 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
14060 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
14070 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14080 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14090 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
140a0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
140b0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
140c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
140d0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
140e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
140f0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
14100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14110 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
14120 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
14130 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
14140 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
14150 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
14160 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
14170 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
14180 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
14190 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
141a0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
141b0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
141c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
141d0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
141e0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
141f0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
14200 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
14210 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
14220 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
14230 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
14240 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
14250 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
14260 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14270 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
14280 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
14290 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
142a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
142b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
142c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
142d0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
142e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
142f0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
14300 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
14310 64 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  dd>^(This option
14320 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14330 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
14340 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
14350 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
14360 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14370 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
14380 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
14390 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
143a0 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
143b0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
143c0 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
143d0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
143e0 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
143f0 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
14400 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
14410 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
14420 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
14430 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
14440 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
14450 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
14460 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
14470 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
14480 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
14490 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
144a0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
144b0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
144c0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
144d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
144e0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
144f0 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
14500 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
14510 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
14520 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
14530 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
14540 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
14550 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
14560 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
14570 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
14580 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
14590 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
145a0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
145b0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
145c0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
145d0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
145e0 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
145f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
14600 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
14610 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
14620 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14630 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14640 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
14650 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14660 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
14670 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  >^This option ta
14680 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
14690 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
146a0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
146b0 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
146c0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
146d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
146e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
146f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
14700 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
14710 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
14720 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54  y optimizer.  ^T
14730 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14740 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
14750 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
14760 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
14770 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
14780 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14790 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
147a0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
147b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
147c0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
147d0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
147e0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
147f0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14800 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14810 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
14820 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
14830 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
14840 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
14850 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
14860 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
14870 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
14880 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
14890 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
148a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
148b0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
148c0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
148d0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
148e0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
148f0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
14900 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
14910 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
14920 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14930 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
14940 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14950 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
14960 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14970 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
14980 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14990 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
149a0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
149b0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
149c0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
149d0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
149e0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
149f0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
14a00 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
14a10 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
14a20 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14a30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14a40 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
14a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
14a60 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
14a70 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
14a80 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
14a90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14aa0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14ab0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
14ac0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
14ad0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
14ae0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14af0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
14b00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
14b10 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
14b20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
14b30 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
14b40 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
14b50 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
14b60 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
14b70 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
14b80 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
14b90 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
14ba0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
14bb0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
14bc0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
14bd0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
14be0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
14bf0 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
14c00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14c10 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
14c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14c30 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
14c40 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14c50 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
14c60 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
14c70 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
14c80 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
14c90 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
14ca0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
14cb0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
14cc0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
14cd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14ce0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
14cf0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
14d00 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14d10 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
14d20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
14d30 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
14d40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
14d50 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
14d60 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
14d70 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
14d80 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14d90 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
14da0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
14db0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
14dc0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
14dd0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
14de0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
14df0 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
14e00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
14e10 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
14e20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
14e30 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
14e40 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
14e50 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
14e60 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
14e70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14e80 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
14e90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14ea0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
14eb0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
14ec0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
14ed0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
14ee0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
14ef0 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
14f00 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
14f10 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
14f20 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
14f30 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
14f40 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
14f50 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
14f60 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
14f70 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
14f80 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14f90 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
14fa0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
14fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14fc0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
14fd0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
14fe0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
14ff0 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
15000 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
15010 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
15020 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
15030 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15040 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63  d mmap size.** c
15050 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
15060 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e   at run-time.  N
15070 6f 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d  or may the maxim
15080 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15090 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74  size.** exceed t
150a0 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
150b0 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
150c0 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
150d0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
150e0 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
150f0 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
15100 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
15110 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
15120 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
15130 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
15140 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
15150 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
15160 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
15170 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15180 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15190 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
151a0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
151b0 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
151c0 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  >^This option is
151d0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
151e0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
151f0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
15200 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  s.** with the [S
15210 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
15220 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
15230 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15240 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
15250 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15260 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
15270 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
15280 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
15290 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
152a0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
152b0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
152c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
152d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
152e0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
152f0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15300 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15310 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
15320 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
15330 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15340 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
15350 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
15360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15370 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
15380 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
15390 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
153a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
153b0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
153c0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
153d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
153e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
153f0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
15400 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
15410 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15420 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15430 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15440 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
15450 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
15460 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
15470 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15480 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
15490 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
154a0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
154b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
154c0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
154d0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
154e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
154f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
15500 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
15510 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15520 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15540 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
15550 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15560 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
15570 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
15580 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
15590 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
155a0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
155b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
155c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
155d0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
155e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
155f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
15600 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
15610 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15620 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15630 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
15640 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
15650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15660 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
15670 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
15680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15690 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
156a0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
156b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
156c0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
156d0 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
156e0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
156f0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
15700 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15710 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
15720 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
15730 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
15740 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15750 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15760 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
15770 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
15780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15790 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
157a0 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
157b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157c0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
157d0 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
157e0 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
157f0 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
15800 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15810 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15820 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
15830 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
15840 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
15850 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
15860 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
15870 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
15880 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
15890 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
158a0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
158b0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
158c0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
158d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
158e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
158f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15900 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
15910 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
15920 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15930 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
15940 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
15950 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
15960 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
15970 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
15980 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
15990 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
159a0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
159b0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
159c0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
159d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
159e0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
159f0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
15a00 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
15a10 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15a20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
15a30 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
15a40 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
15a50 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
15a60 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
15a70 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
15a80 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
15a90 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
15aa0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
15ab0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15ac0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
15ad0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15ae0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
15af0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
15b00 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
15b10 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
15b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
15b30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
15b40 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
15b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
15b60 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
15b70 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
15b80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
15b90 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15ba0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
15bb0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
15bc0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
15bd0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15be0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
15bf0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
15c00 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
15c10 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
15c20 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
15c30 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
15c40 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
15c50 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
15c60 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
15c70 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
15c80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
15c90 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15ca0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
15cb0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
15cc0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
15cd0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
15ce0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
15cf0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
15d00 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
15d10 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
15d20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
15d30 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
15d40 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
15d50 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
15d60 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
15d70 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
15d80 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
15d90 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
15da0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
15db0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
15dc0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15dd0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
15de0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15df0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
15e00 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
15e10 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
15e20 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
15e30 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
15e40 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
15e50 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
15e60 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
15e70 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
15e80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15e90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
15ea0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
15eb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
15ec0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
15ed0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
15ee0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
15ef0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
15f00 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
15f10 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
15f20 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
15f30 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
15f40 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15f50 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
15f60 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
15f70 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
15f80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
15f90 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
15fa0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
15fb0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
15fc0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
15fd0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
15fe0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
15ff0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
16000 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
16010 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16020 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
16030 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16040 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16050 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16060 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
16070 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
16080 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
16090 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
160a0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
160b0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
160c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
160d0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
160e0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
160f0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
16100 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
16110 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16120 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16130 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16140 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16150 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
16160 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16170 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16180 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16190 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
161a0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
161b0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
161c0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
161d0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
161e0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
161f0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16200 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16210 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16220 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16230 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16240 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16250 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16260 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16270 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16280 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16290 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
162a0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
162b0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
162c0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
162d0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
162e0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
162f0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16300 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16310 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16320 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16330 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16340 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16350 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
16360 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16370 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
16380 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16390 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
163a0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
163b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
163c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
163d0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
163e0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
163f0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16400 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16410 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
16420 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
16430 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
16440 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16450 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
16460 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
16470 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
16480 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
16490 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
164a0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
164b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
164c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
164d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
164e0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
164f0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
16500 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16510 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16520 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
16530 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
16540 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16550 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16560 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
16570 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
16580 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
16590 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
165a0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
165b0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
165c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
165d0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
165e0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
165f0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
16600 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
16610 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
16620 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
16630 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
16640 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
16650 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
16660 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
16670 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
16680 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49  ibility..*/.SQLI
16690 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
166a0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
166b0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
166c0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
166d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
166e0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
166f0 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
16700 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
16710 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
16720 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
16730 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
16740 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
16750 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
16760 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
16770 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
16780 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
16790 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
167a0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
167b0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
167c0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
167d0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
167e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
167f0 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
16800 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
16810 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
16820 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
16830 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
16840 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
16850 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
16860 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
16870 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
16880 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
16890 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
168a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
168b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
168c0 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (D) interface re
168d0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
168e0 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73  ] of the .** mos
168f0 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
16900 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
16910 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
16920 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
16930 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
16940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
16950 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f  ** ^Inserts into
16960 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
16970 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
16980 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66  recorded..** ^If
16990 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
169a0 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f  INSERT]s into ro
169b0 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61  wid tables.** ha
169c0 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
169d0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
169e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a   connection D, .
169f0 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
16a00 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
16a10 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72  d(D) returns zer
16a20 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  o..**.** ^(If an
16a30 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
16a40 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
16a50 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
16a60 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
16a70 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
16a80 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
16a90 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
16aa0 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
16ab0 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
16ac0 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
16ad0 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
16ae0 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
16af0 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
16b00 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
16b10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
16b20 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
16b30 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
16b40 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
16b50 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
16b60 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
16b70 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
16b80 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
16b90 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
16ba0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
16bb0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
16bc0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
16bd0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
16be0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
16bf0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
16c00 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
16c10 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16c20 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
16c30 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
16c40 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
16c50 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
16c60 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
16c70 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
16c80 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
16c90 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
16ca0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
16cb0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
16cc0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
16cd0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
16ce0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
16cf0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
16d00 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
16d10 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
16d20 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
16d30 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
16d40 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
16d50 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
16d60 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
16d70 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
16d80 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
16d90 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
16da0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
16db0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
16dc0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
16dd0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
16de0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
16df0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
16e00 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
16e10 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
16e20 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
16e30 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
16e40 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
16e50 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
16e60 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
16e70 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
16e80 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
16e90 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
16ea0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
16eb0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
16ec0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
16ed0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
16ee0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
16ef0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
16f00 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
16f10 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
16f20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
16f30 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16f40 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
16f50 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
16f60 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
16f70 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
16f80 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
16f90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
16fa0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
16fb0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
16fc0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
16fd0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
16fe0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
16ff0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
17000 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
17010 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
17020 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
17030 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
17040 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
17050 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17060 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
17070 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
17080 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17090 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
170a0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
170b0 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
170c0 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
170d0 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
170e0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
170f0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
17100 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
17110 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
17120 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
17130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
17140 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17150 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
17160 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
17170 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
17180 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
17190 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
171a0 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
171b0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
171c0 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
171d0 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
171e0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
171f0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
17200 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17210 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
17220 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
17230 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
17240 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
17250 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
17260 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
17270 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
17280 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
17290 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
172a0 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
172b0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
172c0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
172d0 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
172e0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
172f0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
17300 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
17310 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
17320 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
17330 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
17340 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
17350 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
17360 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
17370 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
17380 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
17390 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
173a0 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
173b0 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
173c0 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
173d0 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
173e0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
173f0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
17400 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
17410 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
17420 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
17430 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
17440 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
17450 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
17460 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
17470 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
17480 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
17490 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
174a0 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
174b0 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
174c0 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
174d0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
174e0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
174f0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
17500 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
17510 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
17520 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
17530 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
17540 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
17550 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
17560 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
17570 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
17580 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
17590 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
175a0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
175b0 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
175c0 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
175d0 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
175e0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
175f0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
17600 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
17610 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
17620 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17630 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
17640 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
17650 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
17660 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
17670 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17680 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17690 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
176a0 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
176b0 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
176c0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
176d0 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
176e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
176f0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
17700 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
17710 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
17720 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
17730 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
17740 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17750 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
17760 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
17770 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17780 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17790 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
177a0 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
177b0 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
177c0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
177d0 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
177e0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
177f0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
17800 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
17810 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
17820 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
17830 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17840 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
17850 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
17860 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
17870 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
17880 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
17890 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
178a0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
178b0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
178c0 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
178d0 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
178e0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
178f0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
17900 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
17910 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
17920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
17930 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
17940 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17950 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17960 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17970 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
17980 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17990 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
179a0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
179b0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
179c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
179d0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
179e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
179f0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
17a00 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17a10 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
17a20 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
17a30 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
17a40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
17a50 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
17a60 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17a70 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
17a80 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17a90 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
17aa0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17ab0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17ac0 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
17ad0 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
17ae0 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
17af0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
17b00 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
17b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17b20 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
17b30 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
17b40 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
17b50 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17b60 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
17b70 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
17b80 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
17b90 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
17ba0 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
17bb0 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
17bc0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
17bd0 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
17be0 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
17bf0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
17c00 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
17c10 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
17c20 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
17c30 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
17c40 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
17c50 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
17c60 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
17c70 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
17c80 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
17c90 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
17ca0 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
17cb0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
17cc0 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
17cd0 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
17ce0 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
17cf0 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
17d00 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
17d10 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
17d20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
17d30 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
17d40 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
17d50 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
17d60 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
17d70 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
17d80 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
17d90 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
17da0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
17db0 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
17dc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
17dd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
17de0 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
17df0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
17e00 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17e10 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
17e20 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
17e30 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
17e40 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
17e50 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17e60 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17e70 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
17e80 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
17e90 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
17ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17eb0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
17ec0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
17ed0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
17ee0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
17ef0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
17f00 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
17f10 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
17f20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
17f30 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17f40 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
17f50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
17f60 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
17f70 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
17f80 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17f90 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
17fa0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
17fb0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
17fc0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
17fd0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
17fe0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
17ff0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
18000 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
18010 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
18020 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
18030 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
18040 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
18050 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
18060 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
18070 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
18080 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
18090 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
180a0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
180b0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
180c0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
180d0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
180e0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
180f0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
18100 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
18110 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
18120 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
18130 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
18140 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
18150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18160 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
18170 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
18180 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
18190 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
181a0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
181b0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
181c0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
181d0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
181e0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
181f0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
18200 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
18210 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
18220 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
18230 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
18240 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
18250 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
18260 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
18270 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
18280 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
18290 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
182a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
182b0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
182c0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
182d0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
182e0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
182f0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
18300 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
18310 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
18320 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
18330 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
18340 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
18350 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
18360 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
18370 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
18380 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
18390 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
183a0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
183b0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
183c0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
183d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
183e0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
183f0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
18400 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
18410 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
18420 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
18430 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
18440 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
18450 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
18460 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
18470 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
18480 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
18490 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
184a0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
184b0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
184c0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
184d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
184e0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
184f0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
18500 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
18510 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
18520 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
18530 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
18540 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18550 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
18560 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18570 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
18580 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
18590 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
185a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
185b0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
185c0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
185d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
185e0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
185f0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
18600 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18610 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
18620 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
18630 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
18640 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
18650 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
18660 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
18670 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
18680 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
18690 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
186a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
186b0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
186c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
186d0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
186e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
186f0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
18700 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18710 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
18720 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
18730 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
18740 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
18750 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
18760 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
18770 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
18780 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
18790 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
187a0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
187b0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
187c0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
187d0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
187e0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
187f0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
18800 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
18810 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
18820 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
18830 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
18840 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
18850 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
18860 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
18870 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
18880 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
18890 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
188a0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
188b0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
188c0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
188d0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
188e0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
188f0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
18900 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
18910 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
18920 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
18930 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
18940 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
18950 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
18960 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
18970 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
18980 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
18990 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
189a0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
189b0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
189c0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
189d0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
189e0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
189f0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
18a00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18a10 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
18a20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
18a30 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
18a40 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
18a50 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
18a60 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
18a70 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
18a80 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
18a90 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
18aa0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
18ab0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
18ac0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
18ad0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
18ae0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
18af0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
18b00 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
18b10 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
18b20 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
18b30 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
18b40 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
18b50 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
18b60 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
18b70 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
18b80 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
18b90 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
18ba0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
18bb0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
18bc0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
18bd0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
18be0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
18bf0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
18c00 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
18c10 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
18c20 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
18c30 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
18c40 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
18c50 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
18c60 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
18c70 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
18c80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
18c90 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
18ca0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
18cb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
18cc0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
18cd0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
18ce0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
18cf0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
18d00 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
18d10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
18d20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
18d30 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
18d40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
18d50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18d60 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
18d70 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
18d80 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
18d90 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
18da0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
18db0 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
18dc0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
18dd0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18de0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
18df0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
18e00 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
18e10 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
18e20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18e30 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
18e40 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
18e50 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
18e60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
18e70 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
18e80 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
18e90 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
18ea0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18eb0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
18ec0 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
18ed0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
18ee0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
18ef0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
18f00 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
18f10 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
18f20 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
18f30 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
18f40 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
18f50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18f60 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
18f70 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
18f80 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
18f90 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
18fa0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
18fb0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
18fc0 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
18fd0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18fe0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
18ff0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
19000 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
19010 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
19020 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19030 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
19040 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
19050 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
19060 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
19070 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
19080 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
19090 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
190a0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
190b0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
190c0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
190d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
190e0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
190f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
19100 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
19110 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
19120 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
19130 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
19140 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
19150 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
19160 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
19170 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
19180 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
19190 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
191a0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
191b0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
191c0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
191d0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
191e0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
191f0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
19200 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
19210 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
19220 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
19230 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
19240 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
19250 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
19260 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
19270 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
19280 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
19290 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
192a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
192b0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
192c0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
192d0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
192e0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
192f0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
19300 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
19310 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
19320 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
19330 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
19340 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19350 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
19360 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
19370 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
19380 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
19390 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
193a0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
193b0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
193c0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
193d0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
193e0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
193f0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
19400 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
19410 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
19420 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
19430 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
19440 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
19450 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
19460 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
19470 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
19480 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
19490 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
194a0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
194b0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
194c0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
194d0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
194e0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
194f0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
19500 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
19510 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
19520 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
19530 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
19540 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
19550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
19560 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
19570 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
19580 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
19590 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
195a0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
195b0 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
195c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
195d0 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
195e0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
195f0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
19600 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
19610 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
19620 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
19630 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
19640 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
19650 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
19660 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
19670 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
19680 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
19690 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
196a0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
196b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
196c0 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
196d0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
196e0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
196f0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
19700 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
19710 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
19720 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
19730 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
19740 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
19750 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
19760 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
19770 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
19780 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
19790 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
197a0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
197b0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
197c0 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
197d0 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
197e0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
197f0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
19800 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
19810 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
19820 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
19830 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
19840 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
19850 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
19860 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19870 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
19880 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
19890 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
198a0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
198b0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
198c0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
198d0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
198e0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
198f0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
19900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
19910 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
19920 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
19930 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
19940 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
19950 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
19960 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
19970 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
19980 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
19990 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
199a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
199b0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
199c0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
199d0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
199e0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
199f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19a00 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
19a10 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19a20 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
19a30 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
19a40 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
19a50 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
19a60 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
19a70 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
19a80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19a90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
19aa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19ab0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
19ac0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19ad0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19af0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19b00 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
19b10 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
19b20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19b30 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
19b40 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
19b50 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
19b60 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19b70 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
19b80 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
19b90 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
19ba0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
19bb0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
19bc0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
19bd0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
19be0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
19bf0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
19c00 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
19c10 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
19c20 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
19c30 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
19c40 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
19c50 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
19c60 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
19c70 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
19c80 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
19c90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
19ca0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
19cb0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
19cc0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
19cd0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
19ce0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
19cf0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
19d00 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
19d10 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
19d20 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
19d30 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
19d40 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
19d50 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
19d60 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
19d70 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
19d80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19d90 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
19da0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
19db0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
19dc0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
19dd0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
19de0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19df0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
19e00 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
19e10 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
19e20 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
19e30 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
19e40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
19e50 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19e60 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
19e70 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
19e80 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
19e90 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
19ea0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
19eb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
19ec0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
19ed0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
19ee0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
19ef0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
19f00 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
19f10 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
19f20 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
19f30 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
19f40 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
19f50 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
19f60 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
19f70 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
19f80 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19f90 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
19fa0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
19fb0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
19fc0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
19fd0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
19fe0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
19ff0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1a000 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1a010 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1a020 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1a030 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1a040 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1a050 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1a060 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1a070 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1a080 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1a090 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1a0a0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1a0b0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1a0c0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1a0d0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1a0e0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a0f0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1a100 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1a110 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a120 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1a130 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1a140 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1a150 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1a160 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1a170 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1a180 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1a190 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1a1a0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1a1b0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1a1c0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1a1d0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1a1e0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1a1f0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1a200 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1a210 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1a220 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1a230 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1a240 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1a250 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1a260 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1a270 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1a280 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1a290 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a2a0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1a2b0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1a2c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1a2d0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1a2e0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1a2f0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1a300 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1a310 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1a320 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1a330 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1a340 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a350 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1a360 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1a370 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1a380 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1a390 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1a3a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1a3b0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1a3c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a3d0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1a3e0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1a3f0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1a400 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1a410 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1a420 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1a430 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1a440 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1a450 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1a460 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a470 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1a480 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1a490 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1a4a0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1a4b0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1a4c0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1a4d0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1a4e0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1a4f0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1a500 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1a510 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1a520 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1a530 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1a540 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a550 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1a560 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1a570 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1a580 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a590 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1a5a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a5b0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1a5c0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a5d0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1a5e0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1a5f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1a600 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1a610 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a620 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1a630 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a640 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1a650 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a660 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1a670 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a680 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1a690 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1a6a0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1a6b0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1a6c0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1a6d0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1a6e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1a6f0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1a700 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1a710 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1a720 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1a730 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1a740 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1a750 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1a760 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1a770 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1a780 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a790 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1a7a0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1a7b0 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1a7c0 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1a7d0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1a7e0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1a7f0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1a800 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1a810 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1a820 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1a830 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1a840 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1a850 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a860 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1a870 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1a880 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1a890 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1a8a0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1a8b0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1a8c0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1a8d0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1a8e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1a8f0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1a900 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1a910 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1a920 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1a930 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a940 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1a950 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1a960 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1a970 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1a980 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1a990 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a9a0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1a9b0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1a9c0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1a9d0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1a9e0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1a9f0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1aa00 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1aa10 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1aa20 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1aa30 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1aa40 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1aa50 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1aa60 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1aa70 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1aa80 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1aa90 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1aaa0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1aab0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1aac0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1aad0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1aae0 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
1aaf0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1ab00 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1ab10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1ab20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1ab30 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1ab40 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1ab50 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1ab60 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1ab70 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1ab80 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1ab90 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1aba0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1abb0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1abc0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1abd0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1abe0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1abf0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1ac00 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1ac10 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1ac20 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1ac30 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1ac40 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1ac50 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
1ac60 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1ac70 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1ac80 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1ac90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1aca0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1acb0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1acc0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1acd0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1ace0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1acf0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1ad00 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1ad10 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1ad20 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1ad30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ad40 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1ad50 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1ad60 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1ad70 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1ad80 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1ad90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1ada0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1adb0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1adc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1add0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1ade0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1adf0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1ae00 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1ae10 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1ae20 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1ae30 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1ae40 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1ae50 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1ae60 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1ae70 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1ae80 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1ae90 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1aea0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1aeb0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1aec0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1aed0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1aee0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1aef0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1af00 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1af10 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1af20 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1af30 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1af40 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1af50 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1af60 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1af70 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1af80 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1af90 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1afa0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1afb0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1afc0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1afd0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1afe0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1aff0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1b000 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1b010 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1b020 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1b030 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1b040 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1b050 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1b060 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1b070 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1b080 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1b090 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1b0a0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1b0b0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1b0c0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1b0d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1b0e0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1b0f0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1b100 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1b110 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1b120 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1b130 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1b140 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1b150 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1b160 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1b170 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1b180 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1b190 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1b1a0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1b1b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1b1c0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1b1d0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1b1e0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1b1f0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1b200 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1b210 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1b220 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1b230 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1b240 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1b250 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1b260 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1b270 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1b280 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1b290 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1b2a0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1b2b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1b2c0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1b2d0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1b2e0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1b2f0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1b300 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1b310 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1b320 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1b330 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1b340 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1b350 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1b360 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1b370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1b380 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1b390 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1b3a0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1b3b0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1b3c0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1b3d0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1b3e0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1b3f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1b400 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1b410 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1b420 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1b430 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1b440 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1b450 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1b460 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1b470 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1b480 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1b490 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1b4a0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1b4b0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1b4c0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1b4d0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1b4e0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1b4f0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1b500 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1b510 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1b520 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1b530 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1b540 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1b550 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1b560 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1b570 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1b580 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b590 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1b5a0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1b5b0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1b5c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b5d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1b5e0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1b5f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1b600 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1b610 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b620 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1b630 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1b640 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1b650 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1b660 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1b670 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1b680 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1b690 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1b6a0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1b6b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b6c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1b6d0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1b6e0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1b6f0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1b700 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1b710 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1b720 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1b730 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1b740 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b750 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1b760 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1b770 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1b780 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1b790 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1b7a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1b7b0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1b7c0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1b7d0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1b7e0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1b7f0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1b800 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1b810 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b820 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1b830 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1b840 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1b850 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1b860 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b870 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1b880 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1b890 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1b8a0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1b8b0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1b8c0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1b8d0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1b8e0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1b8f0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1b900 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1b910 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1b920 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1b930 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1b940 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1b950 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1b960 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1b970 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1b980 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1b990 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1b9a0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1b9b0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1b9c0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1b9d0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1b9e0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1b9f0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1ba00 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1ba10 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1ba20 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1ba30 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ba40 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1ba50 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1ba60 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1ba70 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1ba80 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1ba90 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1baa0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1bab0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1bac0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1bad0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1bae0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1baf0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1bb00 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1bb10 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1bb20 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1bb30 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1bb40 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1bb50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1bb60 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1bb70 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1bb80 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1bb90 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1bba0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1bbb0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1bbc0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1bbd0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1bbe0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1bbf0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1bc00 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1bc10 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  tring.)^.*/.SQLI
1bc20 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1bc30 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1bc40 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53  st char*,...);.S
1bc50 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1bc60 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1bc70 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1bc80 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41  _list);.SQLITE_A
1bc90 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
1bca0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1bcb0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1bcc0 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50   ...);.SQLITE_AP
1bcd0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1bce0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1bcf0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1bd00 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1bd10 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1bd20 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1bd30 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1bd40 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1bd50 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1bd60 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1bd70 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1bd80 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1bd90 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1bda0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1bdb0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1bdc0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1bdd0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1bde0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1bdf0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1be00 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1be10 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1be20 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1be30 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1be40 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1be50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1be60 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1be70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1be80 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1be90 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1bea0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1beb0 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1bec0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1bed0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1bee0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1bef0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1bf00 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1bf10 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1bf20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1bf30 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1bf40 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1bf50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1bf60 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1bf70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1bf80 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1bf90 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1bfa0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1bfb0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1bfc0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1bfd0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1bfe0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1bff0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1c000 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c010 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1c020 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1c030 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1c040 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1c050 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1c060 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1c070 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1c080 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1c090 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1c0a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1c0b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1c0c0 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1c0d0 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1c0e0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1c0f0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1c100 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1c110 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1c120 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1c130 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1c140 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1c150 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1c160 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1c170 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1c180 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1c190 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1c1a0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1c1b0 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1c1c0 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1c1d0 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1c1e0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1c1f0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1c200 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1c210 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1c220 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1c230 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1c240 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1c250 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
1c260 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1c270 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1c280 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1c290 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
1c2a0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
1c2b0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
1c2c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1c2d0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
1c2e0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
1c2f0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
1c300 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
1c310 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
1c320 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c330 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1c340 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1c350 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1c360 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1c370 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1c380 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c390 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
1c3a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1c3b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1c3c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
1c3d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1c3e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c3f0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
1c400 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1c410 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1c420 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1c430 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1c440 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1c450 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
1c460 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1c470 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c480 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
1c490 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c4a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c4b0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1c4c0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1c4d0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1c4e0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1c4f0 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
1c500 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
1c510 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1c520 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1c530 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c540 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1c550 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1c560 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c570 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1c580 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1c590 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1c5a0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1c5b0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
1c5c0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1c5d0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1c5e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1c5f0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1c600 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
1c610 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
1c620 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
1c630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1c640 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1c650 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c660 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1c670 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
1c680 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1c690 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1c6a0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1c6b0 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1c6c0 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1c6d0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1c6e0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1c6f0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1c700 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1c710 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1c720 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1c730 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1c740 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1c750 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1c760 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1c770 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1c780 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1c790 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1c7a0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1c7b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1c7c0 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1c7d0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1c7e0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1c7f0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1c800 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1c810 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1c820 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1c830 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1c840 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1c850 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1c860 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1c870 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1c880 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1c890 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1c8a0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1c8b0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1c8c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1c8d0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1c8e0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1c8f0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1c900 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1c910 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1c920 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1c930 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1c940 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1c950 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1c960 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1c970 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1c980 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1c990 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1c9a0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1c9b0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1c9c0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1c9d0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1c9e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c9f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1ca00 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1ca10 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1ca20 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1ca30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1ca40 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1ca50 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1ca60 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1ca70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1ca80 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1ca90 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1caa0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1cab0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1cac0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1cad0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1cae0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1caf0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1cb00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1cb10 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1cb20 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1cb30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1cb40 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1cb50 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1cb60 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
1cb70 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1cb80 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1cb90 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
1cba0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1cbb0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1cbc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1cbd0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1cbe0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1cbf0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1cc00 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1cc10 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1cc20 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1cc30 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1cc40 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1cc50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1cc60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1cc70 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1cc80 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1cc90 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1cca0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1ccb0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1ccc0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1ccd0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1cce0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1ccf0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1cd00 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1cd10 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1cd20 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1cd30 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1cd40 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1cd50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1cd60 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1cd70 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1cd80 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1cd90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1cda0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1cdb0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1cdc0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1cdd0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1cde0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1cdf0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1ce00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1ce10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1ce20 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1ce30 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1ce40 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1ce50 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1ce60 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1ce70 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1ce80 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1ce90 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1cea0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1ceb0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1cec0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1ced0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1cee0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1cef0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1cf00 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1cf10 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1cf20 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1cf30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1cf40 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1cf50 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1cf60 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1cf70 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cf80 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1cf90 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1cfa0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1cfb0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1cfc0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1cfd0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1cfe0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1cff0 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
1d000 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1d010 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1d020 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
1d030 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1d040 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1d050 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1d060 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1d070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1d080 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1d090 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1d0a0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1d0b0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1d0c0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1d0d0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1d0e0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1d0f0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1d100 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1d110 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1d120 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1d130 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1d140 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1d150 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1d160 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1d170 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1d180 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1d190 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1d1a0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1d1b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1d1c0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1d1d0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1d1e0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1d1f0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1d200 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1d210 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1d220 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1d230 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1d240 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1d250 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1d260 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20  * ^If N is less 
1d270 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 50  than one, then P
1d280 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
1d290 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
1d2a0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
1d2b0 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
1d2c0 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
1d2d0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
1d2e0 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
1d2f0 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68  ess than one, th
1d300 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  en the PRNG is s
1d310 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1d320 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69 6e  omness.** obtain
1d330 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1d340 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1d350 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1d360 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1d370 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  ct..** ^If the p
1d380 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
1d390 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64  this routine had
1d3a0 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f   an N of 1 or mo
1d3b0 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 70  re then.** the p
1d3c0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1d3d0 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1d3e0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1d3f0 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1d400 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1d410 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1d420 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1d430 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1d440 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1d450 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1d460 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1d470 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1d480 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1d490 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1d4a0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1d4b0 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1d4c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1d4d0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1d4e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1d4f0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1d500 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1d510 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1d520 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d530 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1d540 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1d550 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1d560 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1d570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1d580 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1d590 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d5a0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1d5b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1d5c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1d5d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1d5e0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1d5f0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1d600 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1d610 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1d620 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1d630 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1d640 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1d650 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d660 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d670 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1d680 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1d690 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1d6a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d6b0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1d6c0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1d6d0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1d6e0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1d6f0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1d700 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1d710 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1d720 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1d730 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1d740 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1d750 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1d760 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1d770 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1d780 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1d790 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1d7a0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1d7b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d7c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1d7d0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1d7e0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1d7f0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1d800 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1d810 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1d820 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d830 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1d840 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1d850 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1d860 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1d870 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1d880 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1d890 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1d8a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1d8b0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1d8c0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1d8d0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1d8e0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1d8f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d900 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1d910 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1d920 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d930 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1d940 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1d950 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1d960 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1d970 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1d980 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1d990 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1d9a0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1d9b0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1d9c0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1d9d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d9e0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1d9f0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1da00 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1da10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1da20 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1da30 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1da40 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1da50 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1da60 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1da70 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1da80 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1da90 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1daa0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1dab0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1dac0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1dad0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1dae0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1daf0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1db00 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1db10 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1db20 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1db30 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1db40 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1db50 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1db60 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1db70 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1db80 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1db90 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1dba0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1dbb0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1dbc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1dbd0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1dbe0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1dbf0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1dc00 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1dc10 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1dc20 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1dc30 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1dc40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1dc50 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1dc60 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1dc70 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1dc80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1dc90 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1dca0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1dcb0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1dcc0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1dcd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1dce0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1dcf0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1dd00 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1dd10 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1dd20 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1dd30 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1dd40 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1dd50 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1dd60 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1dd70 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1dd80 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1dd90 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1dda0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1ddb0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1ddc0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1ddd0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1dde0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1ddf0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1de00 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1de10 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1de20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1de30 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1de40 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1de50 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1de60 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1de70 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1de80 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1de90 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1dea0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1deb0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1dec0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1ded0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1dee0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1def0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1df00 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1df10 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1df20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1df30 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1df40 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1df50 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1df60 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1df70 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1df80 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1df90 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1dfa0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1dfb0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1dfc0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1dfd0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1dfe0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1dff0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1e000 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1e010 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1e020 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1e030 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1e040 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1e050 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1e060 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1e070 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1e080 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1e090 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1e0a0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1e0b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1e0c0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1e0d0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1e0e0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1e0f0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1e100 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1e110 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1e120 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1e130 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1e140 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1e150 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1e160 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1e170 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1e180 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1e190 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1e1a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1e1b0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1e1c0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1e1d0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1e1e0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1e1f0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1e200 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1e210 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1e220 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1e230 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1e240 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e250 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1e260 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1e270 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1e280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e290 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1e2a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e2b0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1e2c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1e2d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1e2e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e2f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1e300 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1e310 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1e320 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1e330 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1e340 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1e350 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1e360 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1e370 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1e380 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1e390 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1e3a0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1e3b0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1e3c0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1e3d0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1e3e0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1e3f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1e400 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1e410 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1e420 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e430 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1e440 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1e450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e460 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1e470 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1e480 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e490 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1e4a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1e4b0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1e4c0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1e4d0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1e4e0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1e4f0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1e500 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1e510 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1e520 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1e530 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1e540 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1e550 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1e560 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1e570 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1e580 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1e590 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1e5a0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1e5b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1e5c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1e5d0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1e5e0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1e5f0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1e600 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1e610 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1e620 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1e630 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1e640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e650 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1e660 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1e670 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1e680 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1e690 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e6a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1e6b0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1e6c0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1e6d0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1e6e0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1e6f0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1e700 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1e710 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1e720 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1e730 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1e740 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1e750 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1e760 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1e770 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1e780 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1e790 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1e7a0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1e7b0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1e7c0 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  a [SQLITE_ROLLBA
1e7d0 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65  CK | return code
1e7e0 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73  ].** from the [s
1e7f0 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
1e800 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
1e810 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
1e820 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1e830 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1e840 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1e850 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1e860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1e870 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1e880 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1e890 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1e8a0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1e8b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e8c0 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1e8d0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1e8e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1e8f0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
1e900 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
1e910 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1e920 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
1e930 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
1e940 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
1e950 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
1e960 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
1e970 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1e980 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1e990 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
1e9a0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1e9b0 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
1e9c0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1e9d0 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
1e9e0 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
1e9f0 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
1ea00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ea10 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
1ea20 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
1ea30 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
1ea40 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
1ea50 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
1ea60 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
1ea70 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1ea80 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
1ea90 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
1eaa0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1eab0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1eac0 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1ead0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1eae0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1eaf0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1eb00 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1eb10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1eb20 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1eb30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1eb40 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1eb50 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1eb60 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1eb70 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1eb80 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1eb90 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1eba0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1ebb0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1ebc0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1ebd0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1ebe0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1ebf0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1ec00 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1ec10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1ec20 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1ec30 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1ec40 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1ec50 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1ec60 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1ec70 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1ec80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ec90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1eca0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1ecb0 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1ecc0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1ecd0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1ece0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1ecf0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1ed00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ed10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ed20 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1ed30 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1ed40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ed50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ed60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ed70 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1ed80 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1ed90 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1eda0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1edb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1edc0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1edd0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1ede0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1edf0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ee00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ee10 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1ee20 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1ee30 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1ee40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ee50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ee60 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1ee70 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1ee80 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1ee90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1eea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1eeb0 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1eec0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1eed0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1eee0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1eef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ef00 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1ef10 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1ef20 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ef30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ef40 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1ef50 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1ef60 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1ef70 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ef80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ef90 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1efa0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1efb0 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1efc0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1efd0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1efe0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1eff0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1f000 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f010 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f020 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f030 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1f040 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1f050 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1f060 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1f070 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f080 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1f090 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1f0a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f0b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f0c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f0d0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1f0e0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1f0f0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1f100 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f110 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f120 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1f130 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1f140 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1f150 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f160 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f170 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1f180 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1f190 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f1a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f1b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f1c0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1f1d0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1f1e0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f1f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f210 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1f220 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
1f230 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f240 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f250 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f260 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
1f270 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
1f280 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
1f290 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
1f2a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f2b0 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
1f2c0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
1f2d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1f2e0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1f2f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1f300 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1f310 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
1f320 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1f330 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1f350 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
1f360 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
1f370 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
1f380 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
1f3a0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
1f3b0 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
1f3c0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1f3d0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f3e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
1f3f0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1f400 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
1f410 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
1f420 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f430 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
1f440 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1f450 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
1f460 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
1f470 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f480 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
1f490 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1f4a0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
1f4b0 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
1f4c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f4d0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
1f4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
1f4f0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1f500 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f510 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f520 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
1f530 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
1f540 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f550 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f560 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f570 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
1f580 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
1f590 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f5a0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1f5b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f5c0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1f5d0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1f5e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f5f0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1f600 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f610 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1f620 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1f630 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1f640 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1f650 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f660 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1f670 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1f680 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1f690 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1f6a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f6b0 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1f6c0 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1f6d0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1f6e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f6f0 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
1f700 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55        33   /* NU
1f710 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1f720 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f740 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
1f750 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
1f760 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1f770 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1f780 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f790 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1f7a0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1f7b0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1f7c0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1f7d0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1f7e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1f7f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1f800 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1f810 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
1f820 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
1f830 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
1f840 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1f850 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
1f860 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
1f870 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
1f880 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1f890 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1f8a0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
1f8b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
1f8c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1f8d0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
1f8e0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
1f8f0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
1f900 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
1f910 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1f920 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
1f930 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
1f940 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
1f950 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
1f960 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
1f970 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
1f980 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
1f990 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
1f9a0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
1f9b0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
1f9c0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
1f9d0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
1f9e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1f9f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1fa00 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
1fa10 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
1fa20 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
1fa30 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
1fa40 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
1fa50 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
1fa60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1fa70 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1fa80 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1fa90 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1faa0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1fab0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
1fac0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1fad0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
1fae0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
1faf0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1fb00 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
1fb10 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1fb20 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
1fb30 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1fb40 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
1fb50 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1fb60 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
1fb70 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
1fb80 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
1fb90 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
1fba0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
1fbb0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
1fbc0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
1fbd0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
1fbe0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
1fbf0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
1fc00 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
1fc10 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
1fc20 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1fc30 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
1fc40 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
1fc50 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
1fc60 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
1fc70 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1fc80 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1fc90 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1fca0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1fcb0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1fcc0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1fcd0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1fce0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1fcf0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1fd00 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1fd10 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1fd20 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1fd30 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1fd40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
1fd50 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
1fd60 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
1fd70 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
1fd80 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
1fd90 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
1fda0 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
1fdb0 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
1fdc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fdd0 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
1fde0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1fdf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
1fe00 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
1fe10 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
1fe20 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
1fe30 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1fe40 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
1fe50 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1fe60 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1fe70 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
1fe80 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1fe90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fea0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
1feb0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
1fec0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1fed0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
1fee0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
1fef0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
1ff00 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
1ff10 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
1ff20 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
1ff30 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
1ff40 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
1ff50 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
1ff60 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
1ff70 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
1ff80 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
1ff90 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
1ffa0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
1ffb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
1ffc0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
1ffd0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
1ffe0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
1fff0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
20000 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
20010 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
20020 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
20030 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
20040 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
20050 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
20060 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
20070 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
20080 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
20090 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
200a0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
200b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
200c0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
200d0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
200e0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
200f0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
20100 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
20110 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
20120 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
20130 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
20140 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
20150 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
20160 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
20170 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
20180 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
20190 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
201a0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
201b0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
201c0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
201d0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
201e0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
201f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
20200 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
20210 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
20220 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
20230 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
20240 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
20250 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
20260 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
20270 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
20280 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
20290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
202a0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
202b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
202c0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
202d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
202e0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
202f0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
20300 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
20310 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20320 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
20330 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
20340 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
20350 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
20360 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
20370 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
20380 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
20390 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
203a0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
203b0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
203c0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
203d0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
203e0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
203f0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
20400 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
20410 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
20420 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
20430 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
20440 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20450 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
20460 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
20470 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20480 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
20490 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
204a0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
204b0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
204c0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
204d0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
204e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
204f0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
20500 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
20510 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
20520 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
20530 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
20540 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
20550 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
20560 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
20570 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
20580 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
20590 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
205a0 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
205b0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
205c0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
205d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
205e0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
205f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
20600 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
20610 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
20620 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
20630 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
20640 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
20650 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
20660 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
20670 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
20680 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
20690 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
206a0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
206b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
206c0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
206d0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
206e0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
206f0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
20700 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
20710 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
20720 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
20730 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
20740 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
20750 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
20760 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
20770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
20780 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
20790 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
207a0 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
207b0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
207c0 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
207d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
207e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
207f0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
20800 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
20810 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
20820 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
20830 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
20840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20850 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
20860 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
20870 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
20880 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
20890 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
208a0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
208b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
208c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
208d0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
208e0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
208f0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
20900 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
20910 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
20920 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
20930 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
20940 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
20950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20960 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
20970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
20980 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20990 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
209a0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
209b0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
209c0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
209d0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
209e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
209f0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
20a00 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
20a10 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
20a20 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
20a30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
20a40 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
20a50 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
20a60 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
20a70 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
20a80 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20a90 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
20aa0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20ab0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
20ac0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
20ad0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
20ae0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
20af0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
20b00 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20b10 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
20b20 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
20b30 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
20b40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20b50 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20b60 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
20b70 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
20b80 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
20b90 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
20ba0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
20bb0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
20bc0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
20bd0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
20be0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
20bf0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
20c00 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
20c10 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
20c20 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
20c30 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
20c40 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
20c50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
20c60 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
20c70 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20c80 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
20c90 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
20ca0 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
20cb0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
20cc0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
20cd0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
20ce0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
20cf0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
20d00 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20d10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
20d20 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
20d30 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
20d40 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
20d50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
20d60 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
20d70 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
20d80 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
20d90 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
20da0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
20db0 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
20dc0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
20dd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
20de0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
20df0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
20e00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
20e10 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
20e20 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
20e30 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
20e40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20e50 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
20e60 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
20e70 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
20e80 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
20e90 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
20ea0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
20eb0 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
20ec0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
20ed0 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
20ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
20ef0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
20f00 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
20f10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20f20 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
20f30 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
20f40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
20f50 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
20f60 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
20f70 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
20f80 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
20f90 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
20fa0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
20fb0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
20fc0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
20fd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20fe0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
20ff0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
21000 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
21010 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
21020 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21030 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
21040 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
21050 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
21060 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
21070 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
21080 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
21090 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
210a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
210b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
210c0 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
210d0 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
210e0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
210f0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
21100 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
21110 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
21120 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
21130 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21140 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
21150 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
21160 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
21170 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
21180 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
21190 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
211a0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
211b0 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
211c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
211d0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
211e0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
211f0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
21200 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
21210 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
21220 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
21230 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
21240 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
21250 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
21260 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
21270 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
21280 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
21290 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
212a0 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
212b0 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
212c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
212d0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
212e0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
212f0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
21300 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
21310 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
21320 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
21330 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
21340 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
21350 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
21360 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
21370 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
21380 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
21390 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
213a0 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
213b0 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
213c0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
213d0 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
213e0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
213f0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
21400 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
21410 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
21420 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
21430 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
21440 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
21450 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
21460 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
21470 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
21480 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
21490 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
214a0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
214b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
214c0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
214d0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
214e0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
214f0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
21500 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
21510 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
21520 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
21530 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
21540 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
21550 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
21560 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
21570 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
21580 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
21590 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
215a0 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
215b0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
215c0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
215d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
215e0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
215f0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
21600 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
21610 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
21620 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
21630 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
21640 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
21650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
21660 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
21670 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
21680 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
21690 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
216a0 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
216b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
216c0 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
216d0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
216e0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
216f0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
21700 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
21710 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
21720 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
21730 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
21740 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
21750 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
21760 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
21770 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
21780 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
21790 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
217a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
217b0 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
217c0 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
217d0 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
217e0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
217f0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
21800 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
21810 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
21820 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
21830 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
21840 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
21850 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
21860 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
21870 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
21880 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
21890 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
218a0 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
218b0 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
218c0 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
218d0 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
218e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
218f0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
21900 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
21910 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
21920 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
21930 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
21940 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
21950 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
21960 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
21970 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
21980 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
21990 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
219a0 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
219b0 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
219c0 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
219d0 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
219e0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
219f0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
21a00 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
21a10 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
21a20 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
21a30 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
21a40 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
21a50 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
21a60 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
21a70 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
21a80 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
21a90 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
21aa0 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
21ab0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
21ac0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
21ad0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
21ae0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
21af0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
21b00 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
21b10 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
21b20 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
21b30 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
21b40 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
21b50 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
21b60 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
21b70 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
21b80 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
21b90 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
21ba0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
21bb0 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
21bc0 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
21bd0 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
21be0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
21bf0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
21c00 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
21c10 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
21c20 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
21c30 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
21c40 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
21c50 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
21c60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
21c70 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
21c80 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
21c90 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
21ca0 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
21cb0 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
21cc0 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
21cd0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
21ce0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
21cf0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
21d00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21d10 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
21d20 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
21d30 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
21d40 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
21d50 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
21d60 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
21d70 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
21d80 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
21d90 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
21da0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21db0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
21dc0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
21dd0 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
21de0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
21df0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
21e00 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
21e10 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
21e20 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
21e30 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
21e40 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
21e50 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
21e60 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
21e70 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
21e80 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
21e90 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21ea0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
21eb0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
21ec0 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
21ed0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
21ee0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
21ef0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
21f00 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
21f10 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
21f20 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
21f30 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
21f40 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
21f50 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
21f60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21f70 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
21f80 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
21f90 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
21fa0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
21fb0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
21fc0 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
21fd0 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
21fe0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
21ff0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
22000 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
22010 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
22020 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
22030 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
22040 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
22050 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
22060 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
22070 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
22080 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
22090 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
220a0 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
220b0 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
220c0 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
220d0 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
220e0 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
220f0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
22100 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
22110 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
22120 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
22130 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
22140 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
22150 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
22160 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
22170 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
22180 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
22190 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
221a0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
221b0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
221c0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
221d0 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
221e0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
221f0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
22200 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
22210 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
22220 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
22230 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
22240 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
22250 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
22260 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
22270 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22280 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
22290 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
222a0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
222b0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
222c0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
222d0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
222e0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
222f0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
22300 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22310 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
22320 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
22330 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
22340 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
22350 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
22360 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
22370 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
22380 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
22390 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
223a0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
223b0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
223c0 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
223d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
223e0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
223f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
22400 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
22410 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
22420 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
22430 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22440 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
22450 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
22460 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
22470 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
22480 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
22490 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
224a0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
224b0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
224c0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
224d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
224e0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
224f0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
22500 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
22510 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
22520 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
22530 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
22540 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
22550 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
22560 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
22570 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
22580 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
22590 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
225a0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
225b0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
225c0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
225d0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
225e0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
225f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
22600 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
22610 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
22620 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
22630 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
22640 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
22650 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
22660 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
22670 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
22680 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
22690 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
226a0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
226b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
226c0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
226d0 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
226e0 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
226f0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
22700 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
22710 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
22720 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
22730 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
22740 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
22750 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
22760 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
22770 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
22780 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
22790 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
227a0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
227b0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
227c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
227d0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
227e0 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
227f0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
22800 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
22810 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
22820 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
22830 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
22840 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
22850 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
22860 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
22870 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
22880 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
22890 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
228a0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
228b0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
228c0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
228d0 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
228e0 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
228f0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
22900 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
22910 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
22920 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
22930 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
22940 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
22950 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
22960 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22970 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
22980 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
22990 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
229a0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
229b0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
229c0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
229d0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
229e0 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
229f0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
22a00 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
22a10 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22a20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
22a30 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
22a40 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
22a50 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
22a60 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
22a70 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
22a80 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
22a90 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
22aa0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
22ab0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
22ac0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
22ad0 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
22ae0 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
22af0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
22b00 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
22b10 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
22b20 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
22b30 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
22b40 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
22b50 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
22b60 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
22b70 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
22b80 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
22b90 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
22ba0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
22bb0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
22bc0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
22bd0 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
22be0 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
22bf0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
22c00 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
22c10 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
22c20 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
22c30 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
22c40 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
22c50 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
22c60 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
22c70 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
22c80 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
22c90 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
22ca0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
22cb0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
22cc0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
22cd0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
22ce0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
22cf0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
22d00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22d10 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
22d20 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
22d30 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
22d40 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
22d50 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
22d60 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
22d70 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
22d80 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
22d90 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
22da0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
22db0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
22dc0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
22dd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
22de0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
22df0 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
22e00 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
22e10 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
22e20 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
22e30 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
22e40 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
22e50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
22e60 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
22e70 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
22e80 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
22e90 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
22ea0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
22eb0 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
22ec0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
22ed0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
22ee0 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
22ef0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
22f00 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
22f10 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
22f20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
22f30 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
22f40 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
22f50 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
22f60 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
22f70 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
22f80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
22f90 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
22fa0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
22fb0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
22fc0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
22fd0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
22fe0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
22ff0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23000 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
23010 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23020 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
23030 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
23040 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
23050 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
23060 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
23070 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
23080 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
23090 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
230a0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
230b0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
230c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
230d0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
230e0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
230f0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
23100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
23110 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
23120 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
23130 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
23140 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
23150 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
23160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
23170 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
23180 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
23190 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
231a0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
231b0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
231c0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
231d0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
231e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
231f0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
23200 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
23210 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
23220 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
23230 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
23240 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
23250 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
23260 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
23270 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
23280 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
23290 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
232a0 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
232b0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
232c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
232d0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
232e0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
232f0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
23300 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
23310 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23320 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
23330 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
23340 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
23350 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
23360 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
23370 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
23380 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
23390 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
233a0 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
233b0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
233c0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
233d0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
233e0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
233f0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
23400 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
23410 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
23420 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
23430 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
23440 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23450 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
23460 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
23470 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
23480 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
23490 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
234a0 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
234b0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
234c0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
234d0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
234e0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
234f0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
23500 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
23510 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23520 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
23530 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
23540 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
23550 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
23560 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
23570 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
23580 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
23590 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
235a0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
235b0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
235c0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
235d0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
235e0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
235f0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
23600 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
23610 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
23620 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
23630 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
23640 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
23650 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
23660 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
23670 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
23680 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
23690 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
236a0 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
236b0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
236c0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
236d0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
236e0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
236f0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
23700 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
23710 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
23720 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
23730 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
23740 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
23750 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
23760 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
23770 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
23780 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
23790 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
237a0 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
237b0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
237c0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
237d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
237e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
237f0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
23800 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
23810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23820 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23830 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
23840 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
23850 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
23860 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
23870 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
23880 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
23890 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
238a0 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
238b0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
238c0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
238d0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
238e0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
238f0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
23900 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
23910 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23920 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23930 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
23940 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
23950 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
23960 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
23970 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23980 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
23990 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
239a0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
239b0 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
239c0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
239d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
239e0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
239f0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
23a00 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
23a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
23a20 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
23a30 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
23a40 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
23a50 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
23a60 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
23a70 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
23a80 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
23a90 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
23aa0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23ab0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
23ac0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
23ad0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
23ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23af0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
23b00 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
23b10 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
23b20 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
23b30 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
23b40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
23b50 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
23b60 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
23b70 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
23b80 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
23b90 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
23ba0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
23bb0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
23bc0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
23bd0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
23be0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
23bf0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
23c00 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
23c10 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
23c20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23c30 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
23c40 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
23c50 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
23c60 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
23c70 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
23c80 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
23c90 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
23ca0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
23cb0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
23cc0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
23cd0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
23ce0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
23cf0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
23d00 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
23d10 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
23d20 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
23d30 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
23d40 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
23d50 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
23d60 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
23d70 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
23d80 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
23d90 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
23da0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
23db0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
23dc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
23dd0 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
23de0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
23df0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
23e00 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
23e10 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
23e20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
23e30 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
23e40 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
23e50 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
23e60 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
23e70 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
23e80 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
23e90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
23ea0 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
23eb0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
23ec0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
23ed0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
23ee0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
23ef0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
23f00 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
23f10 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
23f20 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
23f30 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
23f40 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
23f50 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
23f60 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
23f70 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
23f80 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
23f90 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
23fa0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
23fb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
23fc0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
23fd0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
23fe0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
23ff0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
24000 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
24010 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
24020 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
24030 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
24040 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
24050 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
24060 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
24070 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
24080 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
24090 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
240a0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
240b0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
240c0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
240d0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
240e0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
240f0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
24100 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
24110 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
24120 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
24130 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
24140 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
24150 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
24160 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
24170 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
24180 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
24190 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
241a0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
241b0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
241c0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
241d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
241e0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
241f0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
24200 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24210 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
24220 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
24230 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
24240 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24250 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
24260 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
24270 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
24280 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
24290 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
242a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
242b0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
242c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
242d0 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
242e0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
242f0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
24300 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
24310 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
24320 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
24330 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
24340 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
24350 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
24360 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
24370 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
24380 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
24390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
243a0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
243b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
243c0 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
243d0 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
243e0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
243f0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
24400 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
24410 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
24420 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
24430 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
24440 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
24450 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24460 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
24470 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
24480 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
24490 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
244a0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
244b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
244c0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
244d0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
244e0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
244f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
24500 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
24510 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
24520 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
24530 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
24540 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
24550 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
24560 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
24570 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
24580 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24590 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
245a0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
245b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
245c0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
245d0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
245e0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
245f0 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
24600 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
24610 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
24620 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24630 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
24640 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
24650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
24660 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
24670 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
24680 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
24690 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
246a0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
246b0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
246c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
246d0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
246e0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
246f0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
24700 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24710 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
24720 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
24730 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
24740 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
24750 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
24760 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
24770 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
24780 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
24790 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
247a0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
247b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
247c0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
247d0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
247e0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
247f0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
24800 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
24810 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
24820 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
24830 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
24840 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
24850 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
24860 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
24870 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
24880 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
24890 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
248a0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
248b0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
248c0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
248d0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
248e0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
248f0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
24900 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
24910 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
24920 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
24930 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
24940 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
24950 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
24960 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
24970 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
24980 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
24990 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
249a0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
249b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
249c0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
249d0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
249e0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
249f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24a00 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
24a10 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
24a20 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
24a30 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
24a40 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
24a50 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
24a60 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
24a70 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
24a80 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
24a90 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
24aa0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
24ab0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
24ac0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
24ad0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
24ae0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
24af0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
24b00 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
24b10 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
24b20 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
24b30 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
24b40 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
24b50 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
24b60 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
24b70 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
24b80 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
24b90 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
24ba0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
24bb0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
24bc0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
24bd0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
24be0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
24bf0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
24c00 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
24c10 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
24c20 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
24c30 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
24c40 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
24c50 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
24c60 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
24c70 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
24c80 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
24c90 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
24ca0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
24cb0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
24cc0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
24cd0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
24ce0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
24cf0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
24d00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
24d10 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
24d20 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
24d30 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
24d40 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
24d50 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
24d60 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
24d70 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
24d80 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
24d90 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
24da0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
24db0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
24dc0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
24dd0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
24de0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
24df0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
24e00 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
24e10 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24e20 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
24e30 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
24e40 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
24e50 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
24e60 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
24e70 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
24e80 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
24e90 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
24ea0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
24eb0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
24ec0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
24ed0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
24ee0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
24ef0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
24f00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
24f10 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
24f20 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
24f30 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
24f40 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
24f50 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
24f60 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
24f70 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
24f80 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
24f90 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
24fa0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
24fb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24fc0 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
24fd0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
24fe0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
24ff0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
25000 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
25010 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
25020 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
25030 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25040 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
25050 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
25060 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
25070 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
25080 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
25090 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
250a0 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
250b0 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
250c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
250d0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
250e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
250f0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
25100 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25110 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25120 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
25130 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
25140 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
25150 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
25160 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25170 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
25180 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
25190 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
251a0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
251b0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
251c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
251d0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
251e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
251f0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
25200 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
25210 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
25220 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
25230 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
25240 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25250 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
25260 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
25270 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
25280 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
25290 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
252a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
252b0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
252c0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
252d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
252e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
252f0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
25300 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
25310 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
25320 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25330 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
25340 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
25350 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
25360 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
25370 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
25380 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
25390 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
253a0 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
253b0 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
253c0 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
253d0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
253e0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
253f0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25400 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
25410 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
25420 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
25430 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
25440 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25450 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
25460 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
25470 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
25480 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25490 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
254a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
254b0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
254c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
254d0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
254e0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
254f0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
25500 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25510 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25520 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
25530 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25540 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
25550 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
25560 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
25570 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
25580 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
25590 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
255a0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
255b0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
255c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
255d0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
255e0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
255f0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25600 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
25610 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
25620 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
25630 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
25640 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
25650 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
25660 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
25670 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
25680 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
25690 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
256a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
256b0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
256c0 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
256d0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
256e0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
256f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
25700 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
25710 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
25720 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
25730 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
25740 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
25750 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
25760 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
25770 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
25780 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25790 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
257a0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
257b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
257c0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
257d0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
257e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
257f0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
25800 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
25810 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25820 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
25830 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
25840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25850 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
25860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
25870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25880 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
25890 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
258a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
258b0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
258c0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
258d0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
258e0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
258f0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
25900 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
25910 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
25920 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
25930 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
25940 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
25950 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
25960 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
25970 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
25980 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
25990 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
259a0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
259b0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
259c0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
259d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
259e0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
259f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25a00 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
25a10 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
25a20 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
25a30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
25a40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
25a50 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
25a60 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
25a70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25a80 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
25a90 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
25aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
25ab0 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
25ac0 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
25ad0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
25ae0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
25af0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
25b00 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
25b10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25b20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
25b30 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
25b40 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
25b50 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
25b60 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
25b70 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25b80 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
25b90 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
25ba0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
25bb0 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
25bc0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
25bd0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
25be0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
25bf0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
25c00 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
25c10 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
25c20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
25c30 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
25c40 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
25c50 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
25c60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
25c70 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
25c80 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
25c90 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
25ca0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
25cb0 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
25cc0 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
25cd0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
25ce0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
25cf0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
25d00 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
25d10 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
25d20 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
25d30 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
25d40 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
25d50 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
25d60 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
25d70 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
25d80 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
25d90 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
25da0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25db0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
25dc0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
25dd0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
25de0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
25df0 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
25e00 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
25e10 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
25e20 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
25e30 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
25e40 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
25e50 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
25e60 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
25e70 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
25e80 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
25e90 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
25ea0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
25eb0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
25ec0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
25ed0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
25ee0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
25ef0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
25f00 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
25f10 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
25f20 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
25f30 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
25f40 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
25f50 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
25f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25f70 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
25f80 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
25f90 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
25fa0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
25fb0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
25fc0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
25fd0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
25fe0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
25ff0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
26000 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
26010 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
26020 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
26030 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
26040 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
26050 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
26060 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
26070 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
26080 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
26090 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
260a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
260b0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
260c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
260d0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
260e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
260f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
26100 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
26110 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
26120 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
26130 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
26140 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
26150 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
26160 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
26170 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
26180 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
26190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
261a0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
261b0 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
261c0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
261d0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
261e0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
261f0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
26200 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
26210 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
26220 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
26230 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
26240 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
26250 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
26260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26270 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
26280 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
26290 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
262a0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
262b0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
262c0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
262d0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
262e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
262f0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
26300 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
26310 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
26320 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
26330 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
26340 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
26350 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
26360 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
26370 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
26380 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
26390 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
263a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
263b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
263c0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
263d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
263e0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
263f0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
26400 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
26410 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
26420 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
26430 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
26440 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
26450 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
26460 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
26470 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
26480 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
26490 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
264a0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
264b0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
264c0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
264d0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
264e0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
264f0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
26500 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
26510 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
26520 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
26530 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
26540 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
26550 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
26560 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
26570 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
26580 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
26590 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
265a0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
265b0 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
265c0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
265d0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
265e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
265f0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
26600 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
26610 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
26620 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
26630 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
26640 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
26650 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
26660 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
26670 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
26680 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
26690 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
266a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
266b0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
266c0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
266d0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
266e0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
266f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
26700 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
26710 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
26720 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
26730 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
26740 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
26750 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
26760 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
26770 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
26780 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
26790 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
267a0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
267b0 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
267c0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
267d0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
267e0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
267f0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
26800 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
26810 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
26820 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
26830 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
26840 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
26850 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
26860 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
26870 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
26880 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
26890 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
268a0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
268b0 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
268c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
268d0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
268e0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
268f0 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
26900 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
26910 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
26920 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
26930 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
26940 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
26950 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
26960 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
26970 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
26980 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26990 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
269a0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
269b0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
269c0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
269d0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
269e0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
269f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26a00 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
26a10 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26a20 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
26a30 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
26a40 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26a50 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26a60 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
26a70 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26a80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26a90 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26aa0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
26ab0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26ac0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
26ad0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26af0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26b00 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26b10 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26b20 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
26b30 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
26b40 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26b50 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
26b60 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
26b70 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
26b80 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26b90 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
26ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26bb0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
26bc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26bd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26be0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26bf0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
26c00 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26c10 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
26c20 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
26c30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26c40 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
26c50 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
26c60 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
26c70 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
26c80 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26c90 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
26ca0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
26cb0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
26cc0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
26cd0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
26ce0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
26cf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
26d00 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
26d10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26d20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
26d30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26d40 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
26d50 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
26d60 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
26d70 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
26d80 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
26d90 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
26da0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
26db0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
26dc0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
26dd0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
26de0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
26df0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
26e00 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
26e10 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
26e20 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
26e30 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
26e40 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
26e50 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
26e60 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
26e70 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
26e80 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
26e90 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
26ea0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
26eb0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
26ec0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
26ed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26ee0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
26ef0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
26f00 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
26f10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26f20 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
26f30 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26f40 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
26f50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
26f60 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
26f70 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
26f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26f90 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
26fa0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
26fb0 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
26fc0 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
26fd0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
26fe0 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
26ff0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
27000 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
27010 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
27020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27030 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
27040 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
27050 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
27060 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
27070 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
27080 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
27090 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
270a0 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
270b0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
270c0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
270d0 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
270e0 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
270f0 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
27100 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
27110 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
27120 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
27130 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
27140 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
27150 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
27160 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
27170 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
27180 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
27190 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
271a0 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
271b0 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
271c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
271d0 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
271e0 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
271f0 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
27200 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
27210 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
27220 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
27230 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
27240 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
27250 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
27260 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
27270 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27280 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
27290 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
272a0 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
272b0 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
272c0 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
272d0 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
272e0 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
272f0 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
27300 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
27310 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27320 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
27330 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
27340 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
27350 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
27360 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
27370 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
27380 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
27390 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
273a0 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
273b0 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
273c0 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
273d0 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
273e0 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
273f0 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
27400 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
27410 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27420 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
27430 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
27440 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
27450 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
27460 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
27470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27480 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
27490 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
274a0 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
274b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
274c0 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
274d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
274e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
274f0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
27500 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
27510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
27520 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
27530 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
27540 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
27550 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27560 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
27570 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27580 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27590 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
275a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
275b0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
275c0 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
275d0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
275e0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
275f0 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
27600 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
27610 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
27620 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
27630 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
27640 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
27650 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
27660 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27670 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
27680 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
27690 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
276a0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
276b0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
276c0 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
276d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
276e0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
276f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
27700 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
27710 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
27720 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
27730 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
27740 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
27750 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
27760 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
27770 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
27780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27790 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
277a0 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
277b0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
277c0 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
277d0 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
277e0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
277f0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
27800 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
27810 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
27820 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
27830 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
27840 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
27850 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
27860 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
27870 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
27880 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
27890 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
278a0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
278b0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
278c0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
278d0 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
278e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
278f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
27900 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
27910 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
27920 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27930 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
27940 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
27950 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
27960 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
27970 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
27980 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
27990 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
279a0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
279b0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
279c0 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
279d0 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
279e0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
279f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
27a00 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
27a10 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
27a20 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
27a30 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
27a40 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
27a50 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
27a60 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
27a70 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
27a80 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
27a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
27aa0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
27ab0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
27ac0 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
27ad0 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
27ae0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27af0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
27b00 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
27b10 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
27b20 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
27b30 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
27b40 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
27b50 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
27b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
27b70 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
27b80 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
27b90 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
27ba0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
27bb0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
27bc0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
27bd0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
27be0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
27bf0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
27c00 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
27c10 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
27c20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
27c30 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
27c40 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
27c50 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
27c60 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
27c70 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
27c80 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
27c90 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
27ca0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
27cb0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
27cc0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
27cd0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
27ce0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
27cf0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
27d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
27d10 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
27d20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
27d30 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
27d40 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
27d50 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
27d60 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
27d70 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
27d80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27d90 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
27da0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
27db0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
27dc0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
27dd0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
27de0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
27df0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
27e00 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
27e10 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
27e20 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
27e30 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
27e40 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
27e50 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27e60 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
27e70 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
27e80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
27e90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27ea0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
27eb0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
27ec0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
27ed0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
27ee0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27ef0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27f00 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
27f10 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27f20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27f30 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
27f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
27f50 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
27f60 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
27f70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27f80 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
27f90 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
27fa0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
27fb0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
27fc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
27fd0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
27fe0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27ff0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
28000 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
28010 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
28020 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
28030 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28040 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
28050 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
28060 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
28070 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
28080 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
28090 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
280a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
280b0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
280c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
280d0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
280e0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
280f0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
28100 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
28110 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
28120 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
28130 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
28140 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
28150 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28160 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
28170 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
28180 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28190 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
281a0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
281b0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
281c0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
281d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
281e0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
281f0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
28200 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
28210 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
28220 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
28230 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
28240 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
28250 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
28260 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
28270 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
28280 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
28290 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
282a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
282b0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
282c0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
282d0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
282e0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
282f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
28300 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
28310 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
28320 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
28330 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
28340 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
28350 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
28360 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
28370 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
28380 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
28390 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
283a0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
283b0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
283c0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
283d0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
283e0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
283f0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
28400 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
28410 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
28420 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
28430 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
28440 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
28450 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
28460 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
28470 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
28480 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
28490 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
284a0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
284b0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
284c0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
284d0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
284e0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
284f0 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
28500 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
28510 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
28520 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
28530 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
28540 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
28550 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
28560 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
28570 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28580 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
28590 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
285a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
285b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
285c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
285d0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
285e0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
285f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
28600 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
28610 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
28620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28630 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
28640 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
28650 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
28660 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
28670 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
28680 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
28690 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
286a0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
286b0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
286c0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
286d0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
286e0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
286f0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
28700 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
28710 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
28720 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
28730 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
28740 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
28750 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
28760 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
28770 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
28780 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
28790 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
287a0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
287b0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
287c0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
287d0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
287e0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
287f0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
28800 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
28810 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
28820 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
28830 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
28840 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
28850 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
28860 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
28870 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
28880 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
28890 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
288a0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
288b0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
288c0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
288d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
288e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
288f0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
28900 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
28910 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
28920 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
28930 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
28940 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
28950 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
28960 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
28970 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
28980 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
28990 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
289a0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
289b0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
289c0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
289d0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
289e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
289f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
28a00 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
28a10 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
28a20 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
28a30 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
28a40 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
28a50 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
28a60 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
28a70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28a80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
28a90 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
28aa0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28ab0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
28ac0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
28ad0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
28ae0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
28af0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
28b00 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
28b10 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
28b20 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
28b30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28b40 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
28b50 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
28b60 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
28b70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
28b80 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
28b90 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
28ba0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
28bb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28bc0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
28bd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28be0 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
28bf0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
28c00 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
28c10 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
28c20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
28c30 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
28c40 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
28c50 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
28c60 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
28c70 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
28c80 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
28c90 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
28ca0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
28cb0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28cc0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
28cd0 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
28ce0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
28cf0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
28d00 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
28d10 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
28d20 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
28d30 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
28d40 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
28d50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
28d60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
28d70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28d80 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
28d90 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
28da0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28db0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
28dc0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
28dd0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
28de0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
28df0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
28e00 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
28e10 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
28e20 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
28e30 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
28e40 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
28e50 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
28e60 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28e70 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
28e80 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
28e90 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
28ea0 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
28eb0 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
28ec0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
28ed0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
28ee0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
28ef0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
28f00 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
28f10 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
28f20 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
28f30 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
28f40 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
28f50 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
28f60 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
28f70 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
28f80 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
28f90 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
28fa0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
28fb0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
28fc0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
28fd0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
28fe0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
28ff0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29000 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
29010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29020 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
29030 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
29040 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
29050 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
29060 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
29070 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
29080 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
29090 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
290a0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
290b0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
290c0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
290d0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
290e0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
290f0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
29100 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
29110 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
29120 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
29130 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
29140 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
29150 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
29160 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
29170 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
29180 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
29190 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
291a0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
291b0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
291c0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
291d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
291e0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
291f0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
29200 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
29210 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
29220 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
29230 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
29240 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
29250 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
29260 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
29270 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
29280 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
29290 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
292a0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
292b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
292c0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
292d0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
292e0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
292f0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
29300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29310 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
29320 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
29330 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
29340 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
29350 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
29360 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
29370 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
29380 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
29390 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
293a0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
293b0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
293c0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
293d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
293e0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
293f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
29400 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
29410 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
29420 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
29430 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
29440 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
29450 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
29460 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
29470 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
29480 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
29490 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
294a0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
294b0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
294c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
294d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
294e0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
294f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29500 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
29510 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29520 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
29530 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29540 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29550 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
29560 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
29570 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
29580 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
29590 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
295a0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
295b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
295c0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
295d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
295e0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
295f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29600 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
29610 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29620 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
29630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
29640 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
29650 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29660 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
29670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29680 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
29690 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
296a0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
296b0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
296c0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
296d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
296e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
296f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29700 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29710 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
29720 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
29730 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
29740 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29750 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
29760 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
29770 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
29780 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
29790 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
297a0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
297b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
297c0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
297d0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
297e0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
297f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
29800 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
29810 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
29820 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
29830 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
29840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29850 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
29860 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
29870 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
29880 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
29890 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
298a0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
298b0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
298c0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
298d0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
298e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
298f0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
29900 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
29910 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
29920 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
29930 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
29940 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
29950 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
29960 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
29970 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
29980 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
29990 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
299a0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
299b0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
299c0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
299d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
299e0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
299f0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
29a00 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
29a10 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
29a20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29a30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
29a40 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
29a50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29a60 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
29a70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
29a80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29a90 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
29aa0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
29ab0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29ac0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
29ad0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29ae0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
29af0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
29b00 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
29b10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29b20 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
29b30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29b40 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
29b50 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
29b60 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
29b70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29b80 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
29b90 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
29ba0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
29bb0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
29bc0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
29bd0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
29be0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
29bf0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
29c00 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
29c10 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
29c20 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
29c30 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
29c40 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
29c50 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
29c60 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
29c70 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
29c80 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
29c90 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
29ca0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
29cb0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
29cc0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
29cd0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
29ce0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
29cf0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
29d00 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
29d10 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
29d20 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
29d30 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
29d40 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
29d50 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
29d60 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
29d70 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
29d80 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
29d90 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
29da0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
29db0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
29dc0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
29dd0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
29de0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
29df0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
29e00 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
29e10 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
29e20 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
29e30 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
29e40 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
29e50 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
29e60 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29e70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
29e80 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
29e90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29ea0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29eb0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
29ec0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29ed0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
29ee0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
29ef0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29f00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
29f10 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29f20 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
29f30 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
29f40 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
29f50 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
29f60 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
29f70 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
29f80 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
29f90 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
29fa0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
29fb0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
29fc0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
29fd0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
29fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
29ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a000 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2a010 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2a020 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2a030 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2a040 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2a050 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2a060 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2a070 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2a080 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2a090 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2a0a0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2a0b0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2a0c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a0d0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2a0e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a0f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a100 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2a110 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a120 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2a130 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2a140 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a150 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a160 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a180 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2a190 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2a1a0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2a1b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a1c0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2a1d0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2a1e0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2a1f0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2a200 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2a210 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2a220 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2a230 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2a240 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2a250 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2a260 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a270 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2a280 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2a290 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2a2a0 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2a2b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2a2c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2a2d0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2a2e0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2a2f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2a300 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2a310 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2a320 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2a330 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2a340 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2a350 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2a360 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2a370 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2a380 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2a390 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2a3a0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2a3b0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2a3c0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2a3d0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2a3e0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2a3f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2a400 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2a410 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2a420 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2a430 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2a440 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2a450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2a460 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2a470 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2a480 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2a490 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2a4a0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2a4b0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2a4c0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2a4d0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2a4e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2a4f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2a500 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2a510 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a520 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2a530 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2a540 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2a550 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2a560 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2a570 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a580 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2a590 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2a5a0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2a5b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a5c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a5d0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2a5e0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2a5f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2a600 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2a610 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2a620 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2a630 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2a640 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2a650 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2a660 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2a670 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2a680 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2a690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a6a0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2a6b0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2a6c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2a6d0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2a6e0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2a6f0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2a700 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2a710 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a720 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2a730 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2a740 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2a750 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2a760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2a770 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2a780 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2a790 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2a7a0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2a7b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2a7c0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2a7d0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2a7e0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2a7f0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2a800 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2a810 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2a820 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2a830 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2a840 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2a850 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2a860 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2a870 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2a880 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2a890 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2a8a0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2a8b0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2a8c0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2a8d0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2a8e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2a8f0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2a900 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2a910 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2a920 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2a930 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2a940 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a950 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a960 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2a970 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2a980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2a990 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a9a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2a9b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a9c0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2a9d0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2a9e0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2a9f0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2aa00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2aa10 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2aa20 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2aa30 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2aa40 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2aa50 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2aa60 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2aa70 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2aa80 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2aa90 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2aaa0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2aab0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2aac0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2aad0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2aae0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2aaf0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2ab00 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2ab10 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2ab20 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2ab30 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2ab40 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2ab50 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2ab60 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2ab70 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2ab80 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ab90 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2aba0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2abb0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2abc0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2abd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2abe0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2abf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2ac00 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2ac10 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2ac20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2ac30 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2ac40 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2ac50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ac60 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2ac70 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2ac80 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2ac90 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2aca0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2acb0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2acc0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2acd0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2ace0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2acf0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2ad00 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2ad10 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2ad20 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2ad30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2ad40 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2ad50 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2ad60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ad70 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2ad80 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2ad90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2ada0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2adb0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2adc0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2add0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2ade0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2adf0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2ae00 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2ae10 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2ae20 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2ae30 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2ae40 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2ae50 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2ae60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ae70 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2ae80 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2ae90 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2aea0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2aeb0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2aec0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2aed0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2aee0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2aef0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2af00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2af10 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2af20 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2af30 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2af40 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2af50 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2af60 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2af70 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2af80 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2af90 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2afa0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2afb0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2afc0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2afd0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2afe0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2aff0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2b000 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2b010 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2b020 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2b030 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2b040 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2b050 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2b060 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2b070 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2b080 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2b090 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2b0a0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2b0b0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2b0c0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2b0d0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2b0e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2b0f0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2b100 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2b110 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2b120 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2b130 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2b140 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2b150 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2b160 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2b170 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2b180 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2b190 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2b1a0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2b1b0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2b1c0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2b1d0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2b1e0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2b1f0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2b200 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2b210 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2b220 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2b230 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2b240 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b250 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2b260 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2b270 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2b280 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2b290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2b2a0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2b2b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b2c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2b2d0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b2e0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2b2f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2b300 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2b310 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2b320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2b330 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2b340 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2b350 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2b360 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b370 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2b380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b390 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2b3a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b3b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2b3c0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2b3d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2b3e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2b3f0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2b400 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2b410 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2b420 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2b430 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b440 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2b450 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2b460 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2b470 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2b480 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2b490 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2b4a0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2b4b0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2b4c0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2b4d0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2b4e0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2b4f0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2b500 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2b510 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2b520 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2b530 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2b540 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b550 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2b560 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2b570 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2b580 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2b590 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2b5a0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2b5b0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2b5c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2b5d0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2b5e0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2b5f0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2b600 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2b610 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2b620 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2b630 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2b640 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2b650 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2b660 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2b670 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2b680 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2b690 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2b6a0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2b6b0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2b6c0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2b6d0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2b6e0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2b6f0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2b700 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2b710 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2b720 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2b730 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2b740 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2b750 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2b760 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2b770 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2b780 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2b790 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2b7a0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2b7b0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2b7c0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2b7d0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2b7e0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2b7f0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2b800 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2b810 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2b820 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2b830 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2b840 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2b850 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2b860 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
2b870 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2b880 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b890 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2b8a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b8b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b8c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b8d0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2b8e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b8f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b900 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2b910 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2b920 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2b930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b940 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2b950 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2b960 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2b970 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2b980 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b990 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2b9a0 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2b9b0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2b9c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2b9d0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b9e0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2b9f0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2ba00 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2ba10 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2ba20 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2ba30 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2ba40 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2ba50 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2ba60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2ba70 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2ba80 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2ba90 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2baa0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2bab0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2bac0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2bad0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2bae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2baf0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2bb00 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2bb10 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2bb20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2bb30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2bb40 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2bb50 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2bb60 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2bb70 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2bb80 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2bb90 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2bba0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2bbb0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2bbc0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2bbd0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2bbe0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2bbf0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2bc00 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2bc10 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2bc20 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2bc30 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2bc40 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2bc50 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2bc60 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2bc70 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2bc80 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2bc90 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2bca0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2bcb0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2bcc0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2bcd0 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2bce0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2bcf0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2bd00 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2bd10 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2bd20 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2bd30 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2bd40 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2bd50 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2bd60 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2bd70 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2bd80 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2bd90 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2bda0 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2bdb0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2bdc0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2bdd0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2bde0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2bdf0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2be00 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2be10 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2be20 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2be30 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2be40 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2be50 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2be60 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2be70 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2be80 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2be90 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2bea0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2beb0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2bec0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2bed0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2bee0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2bef0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2bf00 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2bf10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2bf20 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2bf30 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2bf40 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2bf50 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2bf60 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2bf70 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2bf80 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2bf90 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2bfa0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2bfb0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2bfc0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2bfd0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2bfe0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2bff0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2c000 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2c010 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2c020 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2c030 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2c040 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2c050 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2c060 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2c070 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2c080 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2c090 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2c0a0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2c0b0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2c0c0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2c0d0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2c0e0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2c0f0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2c100 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2c110 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2c120 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2c130 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2c140 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2c150 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2c160 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2c170 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2c180 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2c190 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2c1a0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2c1b0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2c1c0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2c1d0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2c1e0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2c1f0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2c200 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2c210 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2c220 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2c230 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2c240 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2c250 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2c260 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2c270 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2c280 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2c290 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2c2a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2c2b0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2c2c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2c2d0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2c2e0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2c2f0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2c300 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2c310 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2c320 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2c330 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2c340 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2c350 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2c360 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2c370 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2c380 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2c390 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2c3a0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2c3b0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2c3c0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2c3d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2c3e0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2c3f0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2c400 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2c410 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2c420 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2c430 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2c440 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2c450 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2c460 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2c470 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c480 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2c490 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2c4a0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2c4b0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2c4c0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2c4d0 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2c4e0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2c4f0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2c500 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2c510 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2c520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2c530 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2c540 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2c550 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2c560 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2c570 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2c580 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2c590 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2c5a0 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2c5b0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2c5c0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2c5d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2c5e0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2c5f0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2c600 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2c610 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2c620 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2c630 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2c640 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2c650 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2c660 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2c670 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2c680 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2c690 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2c6a0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2c6b0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2c6c0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2c6d0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2c6e0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2c6f0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2c700 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2c710 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2c720 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2c730 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2c740 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2c750 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2c760 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2c770 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2c780 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2c790 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2c7a0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2c7b0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2c7c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2c7d0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2c7e0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2c7f0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2c800 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2c810 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c820 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2c830 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2c840 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2c850 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2c860 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2c870 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2c880 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2c890 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2c8a0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2c8b0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2c8c0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2c8d0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2c8e0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2c8f0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2c900 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2c910 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2c920 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c930 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2c940 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2c950 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2c960 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2c970 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2c980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2c990 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2c9a0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2c9b0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2c9c0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2c9d0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2c9e0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2c9f0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2ca00 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2ca10 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2ca20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2ca30 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2ca40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2ca50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ca60 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2ca70 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2ca80 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2ca90 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2caa0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2cab0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2cac0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2cad0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2cae0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2caf0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2cb00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2cb10 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2cb20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2cb30 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2cb40 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2cb50 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2cb60 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2cb70 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2cb80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2cb90 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2cba0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2cbb0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2cbc0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2cbd0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2cbe0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2cbf0 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2cc00 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2cc10 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2cc20 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2cc30 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2cc40 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2cc50 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2cc60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2cc70 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2cc80 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2cc90 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2cca0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2ccb0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2ccc0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2ccd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2cce0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2ccf0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2cd00 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2cd10 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2cd20 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2cd30 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2cd40 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2cd50 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2cd60 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2cd70 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2cd80 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2cd90 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2cda0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2cdb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2cdc0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2cdd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2cde0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2cdf0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ce00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ce10 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2ce20 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2ce30 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2ce40 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2ce50 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2ce60 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2ce70 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2ce80 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2ce90 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2cea0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2ceb0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2cec0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2ced0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2cee0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2cef0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2cf00 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2cf10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2cf20 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2cf30 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2cf40 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2cf50 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2cf60 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2cf70 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2cf80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2cf90 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2cfa0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2cfb0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2cfc0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2cfd0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2cfe0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2cff0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2d000 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2d010 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2d020 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2d030 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d040 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2d050 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2d060 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2d070 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2d080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d090 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2d0a0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2d0b0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2d0c0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2d0d0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2d0e0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2d0f0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2d100 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2d110 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2d120 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2d130 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2d140 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2d150 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2d160 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2d170 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
2d180 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
2d190 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2d1a0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2d1b0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2d1c0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2d1d0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2d1e0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2d1f0 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2d200 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2d210 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2d220 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2d230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d240 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2d250 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2d260 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2d270 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2d280 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2d290 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d2a0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2d2b0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2d2c0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2d2d0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2d2e0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2d2f0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2d300 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2d310 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2d320 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2d330 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2d340 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2d350 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2d360 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2d370 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2d380 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2d390 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2d3a0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2d3b0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2d3c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2d3d0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2d3e0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2d3f0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2d400 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2d410 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2d420 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2d430 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2d440 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2d450 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2d460 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2d470 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2d480 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d490 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2d4a0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2d4b0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2d4c0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2d4d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d4e0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2d4f0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2d500 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2d510 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2d520 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2d530 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d540 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2d550 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2d560 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2d570 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2d580 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2d590 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2d5a0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2d5b0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2d5c0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2d5d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2d5e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d5f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2d600 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2d610 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2d620 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2d630 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2d640 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2d650 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2d660 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2d670 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2d680 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2d690 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2d6a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2d6b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2d6c0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2d6d0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2d6e0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2d6f0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2d700 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2d710 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2d720 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2d730 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2d740 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2d750 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2d760 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2d770 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2d780 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2d790 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2d7a0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2d7b0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2d7c0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2d7d0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2d7e0 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2d7f0 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2d800 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2d810 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2d820 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2d830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2d840 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2d850 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2d860 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2d870 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2d880 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2d890 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2d8a0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2d8b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2d8c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2d8d0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2d8e0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2d8f0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2d900 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2d910 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2d920 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2d930 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2d940 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2d950 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d960 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2d970 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2d980 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d990 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2d9a0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2d9b0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2d9c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d9d0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2d9e0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2d9f0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2da00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2da10 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2da20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2da30 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2da40 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2da50 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2da60 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2da70 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2da80 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2da90 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2daa0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2dab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dac0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2dad0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2dae0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2daf0 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2db00 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2db10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2db20 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2db30 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2db40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2db50 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2db60 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2db70 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2db80 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2db90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dba0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2dbb0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2dbc0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2dbd0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2dbe0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2dbf0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2dc00 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2dc10 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2dc20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2dc30 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2dc40 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2dc50 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2dc60 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2dc70 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2dc80 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2dc90 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2dca0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2dcb0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2dcc0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2dcd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dce0 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2dcf0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2dd00 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2dd10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2dd20 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2dd30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2dd40 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2dd50 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2dd60 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2dd70 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2dd80 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2dd90 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2dda0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2ddb0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2ddc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2ddd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2dde0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2ddf0 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2de00 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2de10 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2de20 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2de30 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2de40 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2de50 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2de60 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2de70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2de80 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2de90 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2dea0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2deb0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2dec0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2ded0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2dee0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2def0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2df00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2df10 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
2df20 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2df30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2df40 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2df50 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2df60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2df70 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2df80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2df90 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2dfa0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2dfb0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2dfc0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2dfd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2dfe0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2dff0 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2e000 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e010 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2e020 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2e030 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2e040 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2e050 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2e060 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2e070 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2e080 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2e090 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2e0a0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2e0b0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2e0c0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2e0d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2e0e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2e0f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2e100 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2e110 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2e120 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2e130 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
2e140 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
2e150 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
2e160 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
2e170 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
2e180 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
2e190 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2e1a0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
2e1b0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
2e1c0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
2e1d0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
2e1e0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
2e1f0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2e200 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2e210 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2e220 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2e230 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2e240 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2e250 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2e260 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2e270 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2e280 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2e290 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2e2a0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e2b0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2e2c0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2e2d0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2e2e0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2e2f0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2e300 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2e310 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2e320 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2e330 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
2e340 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2e350 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2e360 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
2e370 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
2e380 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2e390 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2e3a0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2e3b0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
2e3c0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
2e3d0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2e3e0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e3f0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2e400 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
2e410 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
2e420 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2e430 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2e440 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
2e450 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2e460 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
2e470 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
2e480 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
2e490 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2e4a0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
2e4b0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2e4c0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
2e4d0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2e4e0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2e4f0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
2e500 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
2e510 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2e520 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2e530 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2e540 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2e550 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2e560 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2e570 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
2e580 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2e590 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
2e5a0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
2e5b0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
2e5c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
2e5d0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2e5e0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2e5f0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2e600 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2e610 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2e620 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
2e630 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2e640 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2e650 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2e660 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2e670 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2e680 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2e690 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
2e6a0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
2e6b0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
2e6c0 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
2e6d0 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
2e6e0 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
2e6f0 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
2e700 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
2e710 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
2e720 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
2e730 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
2e740 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
2e750 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
2e760 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
2e770 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
2e780 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
2e790 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
2e7a0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
2e7b0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
2e7c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2e7d0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
2e7e0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
2e7f0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2e800 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
2e810 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2e820 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
2e830 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e840 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
2e850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e860 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
2e870 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
2e880 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
2e890 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
2e8a0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
2e8b0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
2e8c0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
2e8d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2e8e0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2e8f0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
2e900 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e910 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
2e920 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2e930 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2e940 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
2e950 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
2e960 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
2e970 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
2e980 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
2e990 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2e9a0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2e9b0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
2e9c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e9d0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
2e9e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e9f0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2ea00 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2ea10 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2ea20 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2ea30 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
2ea40 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2ea50 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
2ea60 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2ea70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2ea80 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2ea90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2eaa0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2eab0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2eac0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2ead0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
2eae0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2eaf0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
2eb00 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2eb10 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2eb20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2eb30 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2eb40 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2eb50 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2eb60 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2eb70 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2eb80 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2eb90 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2eba0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
2ebb0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
2ebc0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
2ebd0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
2ebe0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
2ebf0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
2ec00 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
2ec10 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
2ec20 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
2ec30 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
2ec40 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
2ec50 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
2ec60 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
2ec70 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
2ec80 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
2ec90 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
2eca0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
2ecb0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
2ecc0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
2ecd0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
2ece0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2ecf0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
2ed00 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2ed10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2ed20 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2ed30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2ed40 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2ed50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ed60 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2ed70 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2ed80 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
2ed90 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2eda0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
2edb0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
2edc0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2edd0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
2ede0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
2edf0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
2ee00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ee10 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
2ee20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2ee30 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
2ee40 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
2ee50 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
2ee60 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
2ee70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2ee80 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
2ee90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2eea0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
2eeb0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
2eec0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
2eed0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
2eee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2eef0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2ef00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
2ef10 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
2ef20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ef30 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
2ef40 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
2ef50 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2ef60 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
2ef70 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
2ef80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ef90 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
2efa0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2efb0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
2efc0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2efd0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
2efe0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
2eff0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
2f000 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2f010 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2f020 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2f030 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
2f040 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
2f050 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2f060 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2f070 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2f080 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2f090 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2f0a0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2f0b0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
2f0c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
2f0d0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
2f0e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f0f0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
2f100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
2f110 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
2f120 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2f130 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
2f140 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
2f150 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
2f160 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2f170 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
2f180 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
2f190 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
2f1a0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
2f1b0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
2f1c0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
2f1d0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
2f1e0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2f1f0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
2f200 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2f210 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
2f220 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
2f230 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
2f240 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2f250 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f260 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2f270 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f280 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2f290 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2f2a0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2f2b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f2c0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2f2d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2f2e0 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2f2f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f300 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2f310 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2f320 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2f330 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f340 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2f350 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2f360 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2f370 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f380 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
2f390 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2f3a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2f3b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f3c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2f3d0 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
2f3e0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2f3f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2f400 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f410 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2f420 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2f430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f440 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2f450 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f460 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f480 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2f490 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2f4a0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
2f4b0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
2f4c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
2f4d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f4e0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
2f4f0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
2f500 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2f510 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2f520 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2f530 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
2f540 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
2f550 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
2f560 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2f570 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2f580 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2f590 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
2f5a0 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
2f5b0 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
2f5c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2f5d0 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
2f5e0 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
2f5f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
2f600 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
2f610 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
2f620 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2f630 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
2f640 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
2f650 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
2f660 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
2f670 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
2f680 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
2f690 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
2f6a0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2f6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2f6c0 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
2f6d0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2f6e0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2f6f0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
2f700 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
2f710 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
2f720 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
2f730 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
2f740 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
2f750 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
2f760 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2f770 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
2f780 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
2f790 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2f7a0 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
2f7b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2f7c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2f7d0 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
2f7e0 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
2f7f0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
2f800 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
2f810 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2f820 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
2f830 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
2f840 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
2f850 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
2f860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f870 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
2f880 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
2f890 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
2f8a0 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
2f8b0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2f8c0 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
2f8d0 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
2f8e0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2f8f0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2f900 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
2f910 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
2f920 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2f930 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2f940 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
2f950 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
2f960 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
2f970 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
2f980 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
2f990 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
2f9a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2f9b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2f9c0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2f9d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2f9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2f9f0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2fa00 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2fa10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2fa20 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2fa30 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2fa40 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2fa50 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2fa60 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2fa70 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2fa80 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2fa90 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2faa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2fab0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2fac0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2fad0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2fae0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2faf0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2fb00 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2fb10 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2fb20 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2fb30 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2fb40 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2fb50 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2fb60 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2fb70 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2fb80 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2fb90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fba0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2fbb0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2fbc0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2fbd0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2fbe0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2fbf0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2fc00 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2fc10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fc20 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2fc30 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2fc40 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2fc50 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2fc60 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2fc70 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2fc80 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2fc90 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2fca0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2fcb0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2fcc0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2fcd0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2fce0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2fcf0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2fd00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fd10 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2fd20 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2fd30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2fd40 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2fd50 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2fd60 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2fd70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2fd80 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2fd90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2fda0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2fdb0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2fdc0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2fdd0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2fde0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2fdf0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2fe00 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2fe10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2fe20 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2fe30 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2fe40 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2fe50 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2fe60 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2fe70 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2fe80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2fe90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2fea0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2feb0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2fec0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2fed0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2fee0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2fef0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2ff00 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2ff10 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2ff20 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2ff30 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2ff40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2ff50 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2ff60 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2ff70 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2ff80 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2ff90 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2ffa0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2ffb0 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
2ffc0 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
2ffd0 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
2ffe0 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
2fff0 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
30000 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
30010 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
30020 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
30030 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
30040 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
30050 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
30060 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
30070 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
30080 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30090 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
300a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
300b0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
300c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
300d0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
300e0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
300f0 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
30100 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
30110 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
30120 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
30130 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
30140 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30150 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
30160 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
30170 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
30180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
30190 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
301a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
301b0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
301c0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
301d0 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
301e0 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
301f0 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
30200 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
30210 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
30220 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
30230 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
30240 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
30250 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
30260 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
30270 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
30280 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
30290 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
302a0 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
302b0 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
302c0 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
302d0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
302e0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
302f0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
30300 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
30310 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
30320 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
30330 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
30340 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
30350 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
30360 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
30370 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30380 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
30390 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
303a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
303b0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
303c0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
303d0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
303e0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
303f0 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
30400 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
30410 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
30420 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
30430 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
30440 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
30450 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
30460 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
30470 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
30480 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
30490 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
304a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
304b0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
304c0 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
304d0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
304e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
304f0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
30500 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
30510 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
30520 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
30530 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
30540 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68  on should set th
30550 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  is parameter to.
30560 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
30570 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74  LE] if the funct
30580 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
30590 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b  on invokes .** [
305a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
305b0 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16le()] on an 
305c0 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54  input, or [SQLIT
305d0 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68  E_UTF16BE] if th
305e0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
305f0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ion invokes [sql
30600 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30610 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6be()] on an inp
30620 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  ut, or.** [SQLIT
30630 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c  E_UTF16] if [sql
30640 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30650 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72  6()] is used, or
30660 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a   [SQLITE_UTF8].*
30670 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54  * otherwise.  ^T
30680 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
30690 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
306a0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
306b0 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64  times using.** d
306c0 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72  ifferent preferr
306d0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
306e0 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  s, with differen
306f0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
30700 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e  s for.** each en
30710 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e  coding..** ^When
30720 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
30730 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
30740 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
30750 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
30760 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
30770 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
30780 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
30790 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
307a0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
307b0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
307c0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74  arameter may opt
307d0 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
307e0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54  with [SQLITE_DET
307f0 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74  ERMINISTIC].** t
30800 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68  o signal that th
30810 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  e function will 
30820 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
30830 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69  e same result gi
30840 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ven.** the same 
30850 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20  inputs within a 
30860 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
30870 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20  ment.  Most SQL 
30880 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  functions are.**
30890 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
308a0 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72   The built-in [r
308b0 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e  andom()] SQL fun
308c0 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d  ction is an exam
308d0 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63  ple of a.** func
308e0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74  tion that is not
308f0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
30900 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72   The SQLite quer
30910 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c  y planner is abl
30920 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20  e to.** perform 
30930 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d  additional optim
30940 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65  izations on dete
30950 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69  rministic functi
30960 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f  ons, so use.** o
30970 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45  f the [SQLITE_DE
30980 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61  TERMINISTIC] fla
30990 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  g is recommended
309a0 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
309b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
309c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
309d0 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
309e0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
309f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
30a00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
30a10 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
30a20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
30a30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
30a40 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
30a50 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
30a60 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
30a70 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
30a80 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
30a90 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
30aa0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
30ab0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
30ac0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
30ad0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30ae0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
30af0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
30b00 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
30b10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30b20 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
30b30 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
30b40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
30b50 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
30b60 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
30b70 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
30b80 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
30b90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
30ba0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
30bb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
30bc0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
30bd0 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
30be0 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
30bf0 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
30c00 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
30c10 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
30c20 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
30c30 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
30c40 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
30c50 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
30c60 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
30c70 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
30c80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
30c90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30ca0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
30cb0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
30cc0 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
30cd0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
30ce0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
30cf0 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
30d00 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
30d10 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
30d20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
30d30 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
30d40 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
30d50 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
30d60 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
30d70 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
30d80 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
30d90 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
30da0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
30db0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30dc0 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
30dd0 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
30de0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
30df0 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
30e00 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
30e10 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
30e20 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
30e30 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
30e40 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
30e50 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
30e60 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
30e70 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
30e80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30e90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
30ea0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
30eb0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
30ec0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
30ed0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30ee0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
30ef0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
30f00 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
30f10 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
30f20 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
30f30 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
30f40 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
30f50 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
30f60 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
30f70 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
30f80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
30f90 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
30fa0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
30fb0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
30fc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
30fd0 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
30fe0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
30ff0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
31000 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
31010 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
31020 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
31030 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
31040 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
31050 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
31060 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
31070 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
31080 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
31090 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
310a0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
310b0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
310c0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
310d0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
310e0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
310f0 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
31100 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
31110 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
31120 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
31130 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
31140 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
31150 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
31160 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
31170 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
31180 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
31190 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
311a0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
311b0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
311c0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
311d0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
311e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
311f0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
31200 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
31210 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31220 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
31230 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
31240 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
31250 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
31260 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
31270 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
31280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31290 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
312a0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
312b0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
312c0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
312d0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
312e0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
312f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
31300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
31310 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
31320 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
31330 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
31340 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
31350 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
31360 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
31370 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31380 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31390 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
313a0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
313b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
313c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
313d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
313e0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
313f0 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
31400 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
31410 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
31420 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
31430 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
31440 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
31450 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
31460 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
31470 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
31480 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
31490 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
314a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
314b0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
314c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
314d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
314e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
314f0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
31500 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
31510 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31520 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31530 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
31540 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
31550 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
31560 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
31570 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
31580 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
31590 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
315a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
315b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
315c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
315d0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
315e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
315f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31600 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
31610 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
31620 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
31630 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
31640 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
31650 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
31660 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
31670 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
31680 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
31690 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
316a0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
316b0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
316c0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
316d0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
316e0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
316f0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
31700 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
31710 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
31720 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
31730 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
31740 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
31750 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
31760 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
31770 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
31780 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
31790 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
317a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
317b0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
317c0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
317d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
317e0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
317f0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
31800 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
31810 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
31820 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
31830 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
31840 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
31850 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
31860 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
31870 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
31880 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31890 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
318a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
318b0 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
318c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
318d0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
318e0 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
318f0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
31900 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
31910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
31920 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
31930 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
31940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
31950 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
31960 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
31970 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
31980 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
31990 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
319a0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
319b0 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
319c0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
319d0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
319e0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
319f0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
31a00 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
31a10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
31a20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
31a30 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
31a40 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
31a50 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
31a60 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
31a70 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
31a80 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
31a90 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
31aa0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
31ab0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
31ac0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31ad0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
31ae0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
31af0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
31b00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31b10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
31b20 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
31b30 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
31b40 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
31b50 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
31b60 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
31b70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31b80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31b90 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
31ba0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
31bb0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
31bc0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
31bd0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
31be0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
31bf0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
31c00 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
31c10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
31c20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
31c30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
31c40 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
31c50 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
31c60 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
31c70 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
31c80 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
31c90 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
31ca0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
31cb0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
31cc0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
31cd0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
31ce0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
31cf0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
31d00 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
31d10 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
31d20 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
31d30 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
31d40 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
31d50 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
31d60 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
31d70 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
31d80 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
31d90 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
31da0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
31db0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
31dc0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
31dd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31de0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
31df0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31e00 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
31e10 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
31e20 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
31e30 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31e40 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
31e50 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
31e60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
31e70 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
31e80 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
31e90 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
31ea0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31eb0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
31ec0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
31ed0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31ee0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
31ef0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
31f00 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
31f10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
31f20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
31f30 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
31f40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31f50 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
31f60 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
31f70 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
31f80 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
31f90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31fa0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
31fb0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
31fc0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
31fd0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
31fe0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
31ff0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
32000 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
32010 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
32020 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
32030 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
32040 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
32050 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
32060 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
32070 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
32080 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
32090 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
320a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
320b0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
320c0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
320d0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
320e0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
320f0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
32100 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32110 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
32120 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
32130 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
32140 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
32150 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
32160 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
32170 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
32180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32190 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
321a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
321b0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
321c0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
321d0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
321e0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
321f0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
32200 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
32210 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
32220 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
32230 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
32240 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
32250 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
32260 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
32270 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
32280 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
32290 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
322a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
322b0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
322c0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
322d0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
322e0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
322f0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
32300 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
32310 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
32320 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
32330 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
32340 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
32350 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
32360 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
32370 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
32380 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
32390 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
323a0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
323b0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
323c0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
323d0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
323e0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
323f0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
32400 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
32410 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
32420 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
32430 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32440 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
32450 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
32460 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32470 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
32480 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
32490 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
324a0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
324b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
324c0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
324d0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
324e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
324f0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
32500 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32510 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
32520 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
32530 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32540 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32550 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
32560 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
32570 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
32580 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
32590 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
325a0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
325b0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
325c0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
325d0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
325e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
325f0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
32600 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
32610 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32620 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
32630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32640 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
32650 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
32660 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
32670 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
32680 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32690 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
326a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
326b0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
326c0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
326d0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
326e0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
326f0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
32700 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
32710 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
32720 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
32730 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
32740 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
32750 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
32760 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32770 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
32780 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
32790 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
327a0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
327b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
327c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
327d0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
327e0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
327f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
32800 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
32810 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
32820 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32830 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
32840 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32850 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
32860 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
32870 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
32880 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
32890 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
328a0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
328b0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
328c0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
328d0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
328e0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
328f0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
32900 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
32910 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
32920 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32930 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
32940 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
32950 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
32960 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
32970 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
32980 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
32990 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
329a0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
329b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
329c0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
329d0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
329e0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
329f0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
32a00 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32a10 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
32a20 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32a30 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
32a40 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
32a50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
32a60 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
32a70 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
32a80 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
32a90 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
32aa0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
32ab0 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
32ac0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
32ad0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
32ae0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
32af0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
32b00 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
32b10 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
32b20 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
32b30 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
32b40 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
32b50 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
32b60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
32b70 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
32b80 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
32b90 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
32ba0 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
32bb0 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
32bc0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32bd0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
32be0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
32bf0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
32c00 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
32c10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32c20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32c30 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
32c40 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
32c50 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
32c60 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
32c70 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
32c80 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
32c90 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
32ca0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
32cb0 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
32cc0 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
32cd0 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
32ce0 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
32cf0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32d00 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
32d10 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
32d20 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
32d30 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
32d40 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
32d50 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
32d60 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32d70 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
32d80 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
32d90 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
32da0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32db0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
32dc0 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
32dd0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
32de0 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
32df0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
32e00 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
32e10 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
32e20 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
32e30 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32e40 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
32e50 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
32e60 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
32e70 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
32e80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
32e90 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
32ea0 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
32eb0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
32ec0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32ed0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
32ee0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
32ef0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
32f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
32f10 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
32f20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
32f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
32f40 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
32f50 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
32f60 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
32f70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
32f80 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
32f90 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
32fa0 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
32fb0 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
32fc0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
32fd0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
32fe0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
32ff0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
33000 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
33010 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
33020 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
33030 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
33040 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
33050 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33060 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
33070 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
33080 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
33090 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
330a0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
330b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
330c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
330d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
330e0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
330f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
33100 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
33110 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
33120 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
33130 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33140 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33150 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
33160 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33170 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
33180 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
33190 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
331a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
331b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
331c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
331d0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
331e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
331f0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
33200 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
33210 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33220 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
33230 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33240 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
33250 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
33260 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
33270 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
33280 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
33290 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
332a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
332b0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
332c0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
332d0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
332e0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
332f0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
33300 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
33310 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
33320 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
33330 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33340 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
33350 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33360 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
33370 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
33380 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
33390 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
333a0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
333b0 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
333c0 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  PI sqlite3 *sqli
333d0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
333e0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
333f0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
33400 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
33410 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
33420 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  a.**.** These fu
33430 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
33440 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
33450 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
33460 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
33470 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
33480 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
33490 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
334a0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
334b0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
334c0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
334d0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
334e0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
334f0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
33500 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
33510 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
33520 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
33530 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
33540 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
33550 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
33560 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
33570 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
33580 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
33590 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
335a0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
335b0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
335c0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
335d0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
335e0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
335f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33600 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
33610 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
33620 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
33630 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
33640 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
33650 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
33660 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
33670 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
33680 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
33690 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
336a0 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
336b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
336c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
336d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
336e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
336f0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
33700 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
33710 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33720 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
33730 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
33740 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
33750 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33760 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
33770 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
33780 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
33790 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
337a0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
337b0 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
337c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
337d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
337e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
337f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
33800 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33810 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
33820 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
33830 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
33840 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
33850 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
33860 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33870 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
33880 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
33890 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
338a0 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
338b0 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
338c0 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
338d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
338e0 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
338f0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
33900 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
33910 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
33920 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
33930 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
33940 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
33950 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
33960 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
33970 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
33980 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
33990 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
339a0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
339b0 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
339c0 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
339d0 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
339e0 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
339f0 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
33a00 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
33a10 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
33a20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
33a30 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
33a40 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
33a50 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
33a60 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
33a70 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
33a80 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
33a90 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
33aa0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33ab0 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
33ac0 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
33ad0 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
33ae0 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
33af0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33b00 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
33b10 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
33b20 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
33b30 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
33b40 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
33b50 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
33b60 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
33b70 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
33b80 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
33b90 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
33ba0 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
33bb0 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
33bc0 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
33bd0 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
33be0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33bf0 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
33c00 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
33c10 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
33c20 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
33c30 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33c40 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
33c50 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
33c60 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33c70 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
33c80 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
33c90 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
33ca0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
33cb0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
33cc0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
33cd0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
33ce0 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
33cf0 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
33d00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
33d10 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
33d20 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
33d30 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
33d40 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
33d50 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
33d60 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
33d70 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
33d80 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
33d90 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
33da0 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
33db0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
33dc0 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
33dd0 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
33de0 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
33df0 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
33e00 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
33e10 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33e20 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
33e30 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
33e40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
33e50 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
33e60 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
33e70 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
33e80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33e90 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
33ea0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33eb0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
33ec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33ed0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
33ee0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
33ef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33f00 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
33f10 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
33f20 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
33f30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
33f40 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
33f50 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
33f60 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
33f70 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
33f80 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
33f90 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
33fa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33fb0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
33fc0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
33fd0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
33fe0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
33ff0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
34000 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
34010 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
34020 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
34030 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
34040 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
34050 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
34060 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
34070 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
34080 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
34090 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
340a0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
340b0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
340c0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
340d0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
340e0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
340f0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
34100 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
34110 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
34120 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
34130 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
34140 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
34150 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
34160 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
34170 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
34180 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
34190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
341a0 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
341b0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
341c0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
341d0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
341e0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
341f0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
34200 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
34210 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
34220 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
34230 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
34240 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34250 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
34260 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
34270 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
34280 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
34290 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
342a0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
342b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
342c0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
342d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
342e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
342f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
34300 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
34310 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
34320 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
34330 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
34340 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
34350 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
34360 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
34370 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
34380 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
34390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
343a0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
343b0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
343c0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
343d0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
343e0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
343f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34400 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
34410 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
34420 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
34430 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
34440 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34450 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
34460 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
34470 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
34480 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
34490 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
344a0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
344b0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
344c0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
344d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
344e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
344f0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
34500 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
34510 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
34520 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34530 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34540 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
34550 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
34560 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
34570 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
34580 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
34590 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
345a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
345b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
345c0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
345d0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
345e0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
345f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34600 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34610 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
34620 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
34630 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
34640 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
34650 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34660 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
34670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34680 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
34690 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
346a0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
346b0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
346c0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
346d0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
346e0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
346f0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
34700 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
34710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34720 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
34730 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34740 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
34750 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
34760 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
34770 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
34780 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
34790 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
347a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
347b0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
347c0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
347d0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
347e0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
347f0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
34800 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
34810 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
34820 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
34830 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
34840 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34850 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
34860 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34870 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
34880 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
34890 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
348a0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
348b0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
348c0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
348d0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
348e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
348f0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
34900 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
34910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34920 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
34930 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
34940 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
34950 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
34960 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
34970 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
34980 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
34990 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
349a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
349b0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
349c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
349d0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
349e0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
349f0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
34a00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
34a10 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
34a20 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
34a30 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
34a40 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
34a50 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
34a60 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
34a70 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
34a80 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
34a90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34aa0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
34ab0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
34ac0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
34ad0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
34ae0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
34af0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
34b00 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
34b10 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
34b20 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
34b30 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
34b40 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
34b50 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
34b60 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
34b70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34b80 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
34b90 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
34ba0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
34bb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34bc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34bd0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
34be0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
34bf0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
34c00 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
34c10 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
34c20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
34c30 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
34c40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34c50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34c60 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
34c70 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
34c80 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
34c90 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
34ca0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
34cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
34cc0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
34cd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34ce0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34cf0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34d00 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
34d10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34d20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34d30 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
34d40 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
34d50 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
34d60 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
34d70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34d80 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
34d90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34da0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34db0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34dc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34dd0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
34de0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
34df0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
34e00 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
34e10 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
34e20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34e30 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
34e40 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
34e50 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
34e60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34e70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34e80 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
34e90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34ea0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
34eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34ec0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
34ed0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
34ee0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
34ef0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
34f00 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
34f10 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
34f20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
34f30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34f40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
34f50 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
34f60 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
34f70 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
34f80 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
34f90 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
34fa0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
34fb0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
34fc0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
34fd0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
34fe0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
34ff0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
35000 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
35010 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
35020 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
35030 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35040 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
35050 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
35060 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
35070 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35080 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
35090 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
350a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
350b0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
350c0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
350d0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
350e0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
350f0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
35100 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
35110 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
35120 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
35130 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
35140 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
35150 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
35160 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
35170 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
35180 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
35190 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
351a0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
351b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
351c0 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
351d0 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
351e0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
351f0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
35200 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
35210 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
35220 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
35230 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
35240 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
35250 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
35260 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
35270 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
35280 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
35290 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
352a0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
352b0 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
352c0 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
352d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
352e0 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
352f0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
35300 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
35310 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
35320 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
35330 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
35340 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
35350 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
35360 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
35370 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
35380 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35390 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
353a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
353b0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
353c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
353d0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
353e0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
353f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
35400 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
35410 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
35420 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
35430 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
35440 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
35450 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
35460 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
35470 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
35480 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35490 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
354a0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
354b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
354c0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
354d0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
354e0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
354f0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
35500 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
35510 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
35520 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
35530 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
35540 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
35550 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
35560 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
35570 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
35580 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
35590 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
355a0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
355b0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
355c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
355d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
355e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
355f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
35600 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35610 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
35620 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
35630 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
35640 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
35650 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
35660 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
35670 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
35680 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
35690 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
356a0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
356b0 2a 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 76 61 6c 75 65 28 29  3_result_value()
356d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
356e0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
356f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35700 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35710 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
35720 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
35730 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35740 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
35750 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
35760 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
35770 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
35780 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
35790 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
357a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
357b0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
357c0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
357d0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
357e0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
357f0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
35800 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
35810 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
35820 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
35830 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
35840 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
35850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35860 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
35870 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
35880 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
35890 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
358a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
358b0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
358c0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
358d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
358e0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
358f0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
35900 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
35910 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
35920 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
35930 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
35940 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
35950 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
35960 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
35970 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35980 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
35990 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
359a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
359b0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
359c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
359d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
359e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
359f0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
35a00 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35a10 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
35a20 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
35a30 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35a40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
35a50 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
35a60 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53  ext*, double);.S
35a70 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35a90 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
35aa0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
35ab0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
35ac0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35ad0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35af0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35b00 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
35b10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35b20 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
35b30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35b40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
35b50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35b60 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
35b70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35b80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35b90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35ba0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
35bb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
35bc0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
35bd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35be0 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
35bf0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53  ontext*, int);.S
35c00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
35c20 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
35c30 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
35c40 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
35c50 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35c60 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
35c70 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
35c80 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35ca0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35cb0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
35cc0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35cd0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
35ce0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35cf0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
35d00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35d10 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
35d20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35d30 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35d40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35d50 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
35d60 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35d70 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
35d80 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
35d90 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35db0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
35dc0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
35dd0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
35de0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
35df0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35e00 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
35e10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35e30 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35e40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35e50 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
35e60 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
35e70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35e80 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
35e90 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
35ea0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
35eb0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
35ec0 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
35ed0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
35ee0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
35ef0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
35f00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
35f10 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
35f20 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
35f30 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
35f40 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
35f50 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
35f60 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
35f70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
35f80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
35f90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
35fa0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
35fb0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
35fc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
35fd0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
35fe0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
35ff0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
36000 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
36010 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
36020 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
36030 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
36040 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
36050 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
36060 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
36070 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
36080 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
36090 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
360a0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
360b0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
360c0 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
360d0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
360e0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
360f0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
36100 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
36110 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
36120 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
36130 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
36140 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
36150 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
36160 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
36170 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
36180 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
36190 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
361a0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
361b0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
361c0 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
361d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
361e0 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
361f0 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
36200 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
36210 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
36220 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
36230 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
36240 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
36250 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
36260 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
36270 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
36280 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
36290 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
362a0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
362b0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
362c0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
362d0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
362e0 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
362f0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
36300 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
36310 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36320 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
36330 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
36340 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
36350 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
36360 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
36370 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
36380 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
36390 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
363a0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
363b0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
363c0 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
363d0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
363e0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
363f0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
36400 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
36410 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
36420 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
36430 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
36440 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
36450 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
36460 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
36470 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
36480 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
36490 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
364a0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
364b0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
364c0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
364d0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
364e0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
364f0 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
36500 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
36510 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
36520 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
36530 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
36540 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
36550 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
36560 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
36570 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
36580 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
36590 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
365a0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
365b0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
365c0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
365d0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
365e0 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
365f0 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
36600 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
36610 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
36620 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
36630 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
36640 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
36650 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
36660 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
36670 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
36680 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
36690 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
366a0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
366b0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
366c0 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
366d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
366e0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
366f0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
36700 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
36710 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
36720 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
36730 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
36740 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
36750 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
36760 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
36770 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
36780 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36790 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
367a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
367b0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
367c0 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
367d0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
367e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
367f0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
36800 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
36810 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
36820 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
36830 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
36840 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
36850 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
36860 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
36870 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
36880 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36890 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
368a0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
368b0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
368c0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
368d0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
368e0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
368f0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
36900 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
36910 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
36920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
36930 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36940 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
36950 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36960 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
36970 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
36980 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
36990 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
369a0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
369b0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
369c0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
369d0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
369e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
369f0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
36a00 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
36a10 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
36a20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
36a30 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
36a40 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
36a50 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
36a60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
36a70 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
36a80 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
36a90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
36aa0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
36ab0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
36ac0 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
36ad0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36ae0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
36af0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
36b00 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
36b10 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
36b20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36b30 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
36b40 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
36b50 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
36b60 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
36b70 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
36b80 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
36b90 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
36ba0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
36bb0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
36bc0 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
36bd0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
36be0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
36bf0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
36c00 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
36c10 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
36c20 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
36c30 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
36c40 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
36c50 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
36c60 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
36c70 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
36c80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
36c90 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
36ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36cb0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
36cc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
36cd0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
36ce0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
36cf0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36d00 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
36d10 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
36d20 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
36d30 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
36d40 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
36d50 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
36d60 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
36d70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
36d80 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  oid*).);.SQLITE_
36d90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
36da0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36db0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
36dc0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
36dd0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
36de0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
36df0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
36e00 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
36e10 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
36e20 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
36e30 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
36e40 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49  )(void*).);.SQLI
36e50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36e60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36e70 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
36e80 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
36e90 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
36ea0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
36eb0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
36ec0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
36ed0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
36ee0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
36ef0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36f00 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
36f10 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
36f20 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
36f30 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
36f40 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
36f50 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
36f60 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
36f70 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
36f80 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
36f90 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
36fa0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
36fb0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
36fc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
36fd0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36fe0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
36ff0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
37000 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
37010 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37020 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
37030 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
37040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37050 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
37060 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
37070 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
37080 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
37090 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
370a0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
370b0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
370c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
370d0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
370e0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
370f0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
37100 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
37110 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
37120 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
37130 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
37140 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
37150 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
37160 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
37170 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
37180 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
37190 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
371a0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
371b0 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
371c0 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
371d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
371e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
371f0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
37200 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
37210 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
37220 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
37230 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
37240 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37250 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
37260 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
37270 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
37280 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
37290 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
372a0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
372b0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
372c0 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
372d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
372e0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
372f0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
37300 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
37310 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
37320 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
37330 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
37340 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
37350 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
37360 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
37370 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
37380 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
37390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
373a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
373b0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
373c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
373d0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
373e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
373f0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  n_v2()]..*/.SQLI
37400 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37410 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37420 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
37430 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
37440 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
37450 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
37460 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
37470 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37490 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
374a0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
374b0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
374c0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
374d0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
374e0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
374f0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
37500 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
37510 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
37520 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
37530 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
37540 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
37550 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
37560 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
37570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
37580 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
37590 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
375a0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
375b0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
375c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
375d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
375e0 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
375f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37600 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37610 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
37620 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
37630 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
37640 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
37650 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  key */.);.SQLITE
37660 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
37670 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  _key_v2(.  sqlit
37680 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
37690 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
376a0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
376b0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
376c0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
376d0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
376e0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
376f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
37700 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
37710 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
37720 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
37730 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
37740 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
37750 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
37760 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
37770 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
37780 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
37790 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
377a0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
377b0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
377c0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
377d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
377e0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
377f0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
37800 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
37810 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
37820 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
37830 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37840 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
37850 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37870 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37880 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37890 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
378a0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
378b0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
378c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
378d0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32  sqlite3_rekey_v2
378e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
378f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37900 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
37910 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
37920 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
37930 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
37940 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
37950 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
37960 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
37970 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
37980 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
37990 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
379a0 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
379b0 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
379c0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
379d0 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
379e0 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
379f0 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
37a00 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
37a10 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63   void sqlite3_ac
37a20 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
37a30 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
37a40 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
37a50 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
37a60 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
37a70 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
37a80 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
37a90 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
37aa0 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
37ab0 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
37ac0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
37ad0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
37ae0 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
37af0 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
37b00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
37b10 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
37b20 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
37b30 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
37b40 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
37b50 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
37b60 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
37b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
37b80 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
37b90 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
37ba0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37bb0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
37bc0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
37bd0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
37be0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
37bf0 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
37c00 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
37c10 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
37c20 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
37c30 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
37c40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
37c50 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
37c60 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
37c70 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
37c80 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
37c90 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
37ca0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
37cb0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
37cc0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
37cd0 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
37ce0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
37cf0 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
37d00 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
37d10 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
37d20 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
37d30 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
37d40 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
37d50 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
37d60 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
37d70 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
37d80 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37d90 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
37da0 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
37db0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
37dc0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37dd0 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
37de0 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
37df0 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
37e00 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
37e10 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37e20 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
37e30 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
37e40 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
37e50 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
37e60 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
37e70 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  phs..*/.SQLITE_A
37e80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
37e90 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
37ea0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
37eb0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
37ec0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
37ed0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
37ee0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
37ef0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
37f00 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
37f10 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
37f20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
37f30 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
37f40 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
37f50 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
37f60 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
37f70 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
37f80 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
37f90 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
37fa0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
37fb0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
37fc0 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
37fd0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
37fe0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
37ff0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
38000 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
38010 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
38020 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
38030 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
38040 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
38050 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
38060 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
38070 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
38080 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
38090 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
380a0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
380b0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
380c0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
380d0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
380e0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
380f0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
38100 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
38110 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
38120 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
38130 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
38140 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
38150 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
38160 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
38170 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
38180 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
38190 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
381a0 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
381b0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
381c0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
381d0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
381e0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
381f0 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
38200 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
38210 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
38220 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
38230 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
38240 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
38250 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
38260 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
38270 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
38280 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
38290 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
382a0 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
382b0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
382c0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
382d0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
382e0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
382f0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
38300 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
38310 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
38320 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
38330 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
38340 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
38350 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
38360 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
38370 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
38380 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
38390 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
383a0 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
383b0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
383c0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
383d0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
383e0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
383f0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
38400 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
38410 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
38420 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
38430 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ided..**.** <b>N
38440 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
38450 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
38460 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
38470 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
38480 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
38490 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  to calling [sqli
384a0 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71  te3_open] or [sq
384b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20  lite3_open_v2]. 
384c0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
384d0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
384e0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
384f0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
38500 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
38510 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a  .  Here is an.**
38520 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20   example of how 
38530 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67  to do this using
38540 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69   C++ with the Wi
38550 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a  ndows Runtime:.*
38560 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
38570 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54  ><pre>.** LPCWST
38580 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77  R zPath = Window
38590 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c  s::Storage::Appl
385a0 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72  icationData::Cur
385b0 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b  rent->.** &nbsp;
385c0 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f       TemporaryFo
385d0 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61  lder->Path->Data
385e0 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74  ();.** char zPat
385f0 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54  hBuf&#91;MAX_PAT
38600 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d  H + 1&#93;;.** m
38610 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20  emset(zPathBuf, 
38620 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  0, sizeof(zPathB
38630 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61  uf));.** WideCha
38640 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f  rToMultiByte(CP_
38650 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20  UTF8, 0, zPath, 
38660 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69  -1, zPathBuf, si
38670 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a  zeof(zPathBuf),.
38680 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55  ** &nbsp;     NU
38690 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71  LL, NULL);.** sq
386a0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
386b0 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d  tory = sqlite3_m
386c0 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61  printf("%s", zPa
386d0 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65  thBuf);.** </pre
386e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
386f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  /.SQLITE_API SQL
38700 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
38710 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
38720 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
38730 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
38740 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
38750 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 69  ding Database Fi
38760 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
38770 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
38780 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
38790 6f 69 6e 74