System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 249a70accd48e96a92f5a386c526d2d5db4bf37a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 31 36 22 0a 23 64 65 66 69 6e 65 20 53  .7.16".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 36 0a 23 64 65  MBER 3007016.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33  CE_ID      "2013
1070: 2d 30 33 2d 31 33 20 30 30 3a 31 33 3a 32 35 20  -03-13 00:13:25 
1080: 38 33 39 61 61 39 31 66 61 66 31 64 62 37 30 32  839aa91faf1db702
1090: 35 64 39 30 66 61 33 63 36 35 65 35 30 65 66 62  5d90fa3c65e50efb
10a0: 38 32 39 62 30 35 33 62 22 0a 0a 2f 2a 0a 2a 2a  829b053b"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2fc0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2fd0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2fe0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2ff0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
3000: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f   handles], and/o
3030: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61  r.** [sqlite3_ba
3040: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68  ckup] objects th
3050: 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51  en it returns SQ
3060: 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20  LITE_OK but the 
3070: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3080: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3090: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
30a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
30b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
30c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
30d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
30e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
30f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3100: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3110: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3120: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3130: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3140: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3150: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3160: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3170: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3180: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3190: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
31a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
31c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
31d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
31e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
31f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3200: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3210: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3220: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3230: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3240: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3250: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3260: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3270: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3280: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3290: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
32a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
32b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
32c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
32d0: 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  op..*/.SQLITE_AP
32e0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
32f0: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  ose(sqlite3*);.S
3300: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3320: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3330: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3340: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3350: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
3360: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
3370: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
3380: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
3390: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
33a0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
33b0: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
33c0: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
33d0: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
33e0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
33f0: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3400: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3410: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3420: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3430: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
3440: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
3450: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   is a convenienc
3460: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
3470: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
3480: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3490: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
34a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
34b0: 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20  ize()],.** that 
34c0: 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63  allows an applic
34d0: 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c  ation to run mul
34e0: 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73  tiple statements
34f0: 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f   of SQL.** witho
3500: 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65  ut having to use
3510: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65   a lot of C code
3520: 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  . .**.** ^The sq
3530: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3540: 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f  erface runs zero
3550: 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65   or more UTF-8 e
3560: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63  ncoded,.** semic
3570: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51  olon-separate SQ
3580: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3590: 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64  sed into its 2nd
35a0: 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e   argument,.** in
35b0: 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20   the context of 
35c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35d0: 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64  nnection] passed
35e0: 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a   in as its 1st.*
35f0: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
3600: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
3610: 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72  nction of the 3r
3620: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
3630: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3640: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3650: 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  n it is invoked 
3660: 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20  for each result 
3670: 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75  row.** coming ou
3680: 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74  t of the evaluat
3690: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
36a0: 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  s.  ^The 4th arg
36b0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65  te3_exec() is re
36d0: 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f  layed through to
36e0: 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e   the 1st argumen
36f0: 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c  t of each.** cal
3700: 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e  lback invocation
3710: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
3720: 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ack pointer to s
3730: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3740: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e   is NULL, then n
3750: 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76  o callback is ev
3760: 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72  er invoked and r
3770: 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a  esult rows are.*
3780: 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  * ignored..**.**
3790: 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
37a0: 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75  curs while evalu
37b0: 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74  ating the SQL st
37c0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
37d0: 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
37e0: 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65  exec(), then exe
37f0: 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
3800: 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20  rrent statement 
3810: 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62  stops and.** sub
3820: 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e  sequent statemen
3830: 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20  ts are skipped. 
3840: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3850: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3860: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e  3_exec().** is n
3870: 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79  ot NULL then any
3880: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
3890: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
38a0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
38b0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
38c0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61  malloc()] and pa
38d0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
38e0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
38f0: 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ter..** To avoid
3900: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74   memory leaks, t
3910: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
3920: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71  hould invoke [sq
3930: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
3940: 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   on error messag
3950: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
3960: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3970: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a  th parameter of.
3980: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  ** of sqlite3_ex
3990: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
39a0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
39b0: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
39c0: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
39d0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
39e0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
39f0: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3a00: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3a10: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3a30: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3a40: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3a50: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3a60: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3a70: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3a90: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3aa0: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3ab0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3ac0: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3ad0: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3ae0: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3af0: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3b00: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3b10: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3b20: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3b30: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3b40: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3b50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3b60: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3b70: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3b80: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3b90: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3ba0: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3bb0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3bc0: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3bd0: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3be0: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3bf0: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3c00: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3c10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3c20: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3c30: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3c40: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3c50: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3c60: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3c70: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3c80: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3c90: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3ca0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3cb0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3cc0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3cd0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3cf0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3d00: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3d10: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3d20: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3d30: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3d40: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3d50: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3d60: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3d70: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3d80: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3d90: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3da0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3db0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3dc0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3dd0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3de0: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3df0: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3e00: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3e10: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3e20: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3e30: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3e40: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3e50: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3e60: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3e70: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3e80: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3e90: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
3ea0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3eb0: 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20  ion must insure 
3ec0: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
3ed0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3ee0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
3ef0: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
3f00: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
3f20: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3f30: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
3f40: 73 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  se [database con
3f50: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
3f60: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68  ed by.**      th
3f70: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3f80: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3f90: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3fa0: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3fb0: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  g..** <li> The a
3fc0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3fd0: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53  not modify the S
3fe0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
3ff0: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  t passed into.**
4000: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61        the 2nd pa
4010: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
4020: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
4030: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
4040: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f  s running..** </
4050: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul>.*/.SQLITE_AP
4060: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
4070: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
40b0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
40c0: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  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 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
40f0: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4100: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4110: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4120: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4130: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4140: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4150: 20 20 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 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
4180: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
4190: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
41c0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
41d0: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
41e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
41f0: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4200: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4210: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4220: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4230: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4240: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4250: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
4260: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
4270: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
4280: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
4290: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
42a0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
42b0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
42c0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
42d0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
42e0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
42f0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4300: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4310: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4320: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4330: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4340: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4350: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
4360: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
4370: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
4380: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
4390: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
43a0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
43b0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
43c0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
43d0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
43e0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4400: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4410: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4420: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4440: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4450: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4460: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4470: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4480: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4490: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
44a0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
44b0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44c0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
44d0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
44e0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44f0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4510: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4520: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4530: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4560: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4570: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4580: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4590: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
45a0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
45b0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
45c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45d0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
45e0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45f0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4600: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4620: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4630: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4640: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4650: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4660: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4670: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4680: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4690: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
46a0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
46b0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
46c0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
46d0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
46e0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46f0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4700: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4710: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4720: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4730: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4760: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4770: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4780: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4790: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47a0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
47b0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
47c0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
47d0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
47e0: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47f0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4800: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4810: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4830: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4840: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4850: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4860: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4870: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4880: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4890: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
48a0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
48b0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
48c0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
48d0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48f0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4900: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4910: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4920: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4930: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4940: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4950: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4970: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4980: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4990: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
49a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49b0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
49c0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
49d0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
49e0: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4a00: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4a10: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4a20: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4a30: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4a40: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a50: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a60: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a80: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a90: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4aa0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4ab0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4ad0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4ae0: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4af0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4b00: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4b20: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4b30: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4b40: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4b50: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4b60: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4b70: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4b80: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4b90: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4ba0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4bb0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4bc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4bd0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4be0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4bf0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4c00: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4c10: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4c20: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4c30: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c40: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
4c50: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4c60: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4c70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4c80: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4c90: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4ca0: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4cb0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4cc0: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4cd0: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4ce0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4cf0: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4d00: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4d10: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4d20: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4d30: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4d40: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4d50: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4d60: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4d70: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4d80: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4d90: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4da0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4db0: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4dc0: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4dd0: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4de0: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4df0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4e00: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4e10: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4e20: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4e30: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
4e40: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4e50: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4e60: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
4e70: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
4e80: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
4e90: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4ea0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4eb0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4ec0: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4ed0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4ef0: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4f00: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4f10: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4f20: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4f30: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4f40: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4f50: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4f60: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4f70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4f80: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4f90: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4fa0: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4fb0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4fc0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4fd0: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4fe0: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4ff0: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
5000: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
5010: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
5020: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
5030: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5040: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
5050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5060: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5070: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
5080: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
5090: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
50a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
50b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
50c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
50d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
50e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50f0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5100: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5110: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5120: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5130: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5140: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5150: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5160: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5170: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
5180: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5190: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
51a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51b0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
51c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51d0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
51e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51f0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5200: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5210: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5230: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5240: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5250: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5270: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
5280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5290: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
52a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52b0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
52c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52d0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
52e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52f0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5300: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5310: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5330: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5340: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5350: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
5380: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
5390: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53b0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
53c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53d0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53f0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
5400: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5410: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5430: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5450: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5470: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
5480: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5490: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54b0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
54c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54d0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54f0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5500: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5510: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5530: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5540: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5550: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5570: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
5580: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5590: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
55a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55b0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
55c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55d0: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
55e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
55f0: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5600: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5610: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5630: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5640: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5650: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5670: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5680: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5690: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
56a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56b0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
56c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
56d0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
56e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56f0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5700: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5710: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5720: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5730: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5740: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5750: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5760: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5770: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5780: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5790: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
57a0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
57b0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
57c0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
57d0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
57e0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
57f0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5800: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5810: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5820: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
5840: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
5850: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
5860: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
5870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5880: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5890: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
58a0: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
58d0: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
58e0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
58f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5900: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5910: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
5920: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5930: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5940: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5950: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
5960: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5970: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
5980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5990: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
59a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
59b0: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
59c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59d0: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
59e0: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
59f0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5a00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
5a20: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
5a30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a40: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5a50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a60: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
5a70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a80: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
5a90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5aa0: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
5ab0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5ac0: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5ad0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5ae0: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5af0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5b00: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5b10: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5b20: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5b30: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5b40: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5b50: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5b60: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5b70: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5b80: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5b90: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5ba0: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5bc0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5bd0: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5be0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5bf0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5c00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c10: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5c20: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5c30: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5c40: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5c50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c60: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5c70: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5c80: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5c90: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cb0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5cc0: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5cd0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cf0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5d00: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5d10: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5d20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d30: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5d40: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5d50: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d70: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5d80: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5d90: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5da0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5db0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5dc0: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
5dd0: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
5de0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5df0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5e00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e10: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5e20: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5e30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e50: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5e60: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5e70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5ea0: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5eb0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ed0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5ee0: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5ef0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f10: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5f20: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5f30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f50: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5f60: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5f70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f90: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5fa0: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5fb0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fd0: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5fe0: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5ff0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6000: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6010: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6020: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
6030: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
6040: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6050: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6060: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6070: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6080: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6090: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
60a0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
60b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
60c0: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
60d0: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
60e0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
60f0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6100: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6110: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
6120: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
6130: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
6140: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
6150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6160: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
6170: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6180: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6190: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
61a0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
61b0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
61c0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
61d0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
61e0: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
61f0: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6200: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6210: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
6220: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
6230: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
6240: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
6250: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
6260: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
6270: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6280: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6290: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
62a0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
62b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
62c0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
62d0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
62e0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
62f0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6300: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6310: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
6320: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6330: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6340: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6350: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
6360: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6370: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6380: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6390: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
63a0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
63b0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
63c0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
63d0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
63e0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
63f0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6400: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6410: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
6420: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6430: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6440: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6450: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
6460: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6470: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6480: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6490: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
64a0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
64b0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
64c0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
64d0: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
64e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
64f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6500: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6510: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
6520: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
6530: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
6540: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
6550: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
6560: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
6570: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6580: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6590: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
65a0: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
65b0: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
65c0: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
65d0: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
65e0: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
65f0: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6600: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6610: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6630: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6650: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6660: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6670: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6680: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
66a0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
66b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
66c0: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
66d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6700: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6710: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
6720: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6730: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6740: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6760: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6770: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6780: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6790: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
67a0: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
67b0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
67c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67d0: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
67e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
67f0: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6800: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6810: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6820: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6830: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6840: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6850: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6860: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6870: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6880: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6890: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
68a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
68b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
68c0: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
68d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
68e0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
68f0: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6900: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6910: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6920: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6930: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6940: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6950: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
6960: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
6970: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6980: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6990: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
69a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
69b0: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
69c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69d0: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
69e0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
69f0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6a00: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6a10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
6a20: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
6a30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6a40: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
6a50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6a60: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
6a70: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6a80: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6a90: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6aa0: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6ab0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6ac0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6ad0: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6ae0: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6af0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6b00: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6b10: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6b20: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6b30: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6b40: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6b50: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6b60: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6b70: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6b80: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6b90: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6ba0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6bb0: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6bc0: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6bd0: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6be0: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6bf0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6c00: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6c10: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6c20: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6c30: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6c40: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6c50: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6c60: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6c70: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6c80: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6c90: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6ca0: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6cb0: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6cc0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6cd0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6ce0: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6cf0: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6d00: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6d10: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6d20: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
6d30: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
6d40: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
6d50: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
6d60: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
6d70: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
6d80: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
6d90: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
6da0: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
6db0: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
6dc0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6dd0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
6de0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
6df0: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
6e00: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
6e10: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
6e20: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
6e30: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
6e40: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
6e50: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
6e60: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
6e70: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
6e80: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
6e90: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6ea0: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
6eb0: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
6ec0: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
6ed0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6ee0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6ef0: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
6f00: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
6f10: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
6f20: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
6f30: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
6f40: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
6f50: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
6f60: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
6f70: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6f80: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6f90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6fa0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
6fb0: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
6fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6fd0: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
6fe0: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
6ff0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7000: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
7010: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
7020: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7030: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7040: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7050: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7060: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
7070: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7080: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7090: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
70a0: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
70b0: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
70c0: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
70d0: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
70e0: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
70f0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7100: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7110: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
7120: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7130: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7140: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7150: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7160: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
7170: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7180: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7190: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
71a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
71b0: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
71c0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
71d0: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
71e0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
71f0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7200: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7210: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
7220: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7230: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7240: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7250: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7260: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
7270: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7280: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7290: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
72a0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
72b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
72c0: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
72d0: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
72e0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
72f0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7300: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7310: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
7320: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7330: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7340: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7350: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7360: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
7370: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7380: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7390: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
73a0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73b0: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
73c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
73d0: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
73e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
73f0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7400: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7410: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
7420: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7430: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7440: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7450: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7460: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7470: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7480: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7490: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
74a0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
74b0: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
74c0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
74d0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
74e0: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
74f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7500: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7510: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7520: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7530: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7540: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7550: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
7560: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
7570: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7580: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7590: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
75a0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
75b0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
75c0: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
75d0: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
75e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
75f0: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7600: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7610: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
7620: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7630: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7640: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7650: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
7660: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
7670: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7680: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7690: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
76a0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
76b0: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
76c0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
76d0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
76e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
76f0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7700: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7710: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
7720: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7730: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7740: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7750: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
7760: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
7770: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7780: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7790: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
77a0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
77b0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
77c0: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
77d0: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
77e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
77f0: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7800: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7810: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7820: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7830: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7840: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7850: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
7860: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
7870: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7880: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7890: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
78a0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
78b0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
78c0: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
78d0: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
78e0: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
78f0: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7900: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7910: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7920: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7930: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7940: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7950: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
7960: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
7970: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7980: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7990: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
79a0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
79b0: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
79c0: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
79d0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
79e0: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
79f0: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7a00: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7a10: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
7a20: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
7a30: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
7a40: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
7a50: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
7a60: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
7a70: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7a80: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7a90: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7aa0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7ab0: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7ac0: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7ad0: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7ae0: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7af0: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7b00: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7b10: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7b20: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7b30: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7b40: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7b50: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7b60: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7b70: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7b80: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7b90: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7ba0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7bb0: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7bc0: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7bd0: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7be0: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7bf0: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7c00: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7c10: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7c20: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7c30: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7c40: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7c50: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7c60: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7c70: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7c80: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7c90: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7ca0: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7cb0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7cc0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7cd0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7ce0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7cf0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7d00: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7d10: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7d20: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7d30: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7d40: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7d50: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7d60: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7d70: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7d80: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7d90: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7da0: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
7db0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
7dc0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
7dd0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7de0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
7df0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7e00: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7e10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e20: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7e30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e40: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7e50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e60: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7e70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e80: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7e90: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7ea0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
7eb0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7ec0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
7ed0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7ee0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
7ef0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7f00: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7f10: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7f20: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7f30: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7f40: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7f50: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7f60: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7f70: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7f80: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7f90: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7fa0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
7fb0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
7fc0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
7fd0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
7fe0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
7ff0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
8000: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
8010: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
8020: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
8030: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
8040: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8050: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8060: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
8070: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8080: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8090: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
80a0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
80b0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
80c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
80d0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
80e0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
80f0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8100: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8110: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
8120: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
8130: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
8140: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
8150: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
8160: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
8170: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8180: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8190: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
81a0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
81b0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
81c0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
81d0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
81e0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
81f0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8200: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8210: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
8220: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
8230: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
8240: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
8250: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8260: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
8270: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8280: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8290: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
82a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
82b0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
82c0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
82d0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
82e0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
82f0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8300: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8310: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8320: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
8330: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
8340: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8350: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8360: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
8370: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8380: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8390: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
83a0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
83b0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
83c0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
83d0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
83e0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
83f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8400: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8410: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
8420: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8430: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
8440: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
8450: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8460: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
8470: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8480: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8490: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
84a0: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
84b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
84c0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
84d0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
84e0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
84f0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8500: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8510: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8520: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
8530: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8540: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
8550: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
8560: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8570: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8580: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8590: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
85a0: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
85b0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
85c0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
85d0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
85e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
85f0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8600: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8610: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
8620: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8640: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8650: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
8660: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
8670: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8680: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8690: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
86a0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
86b0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
86c0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
86d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
86e0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
86f0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8700: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
8710: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
8720: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
8730: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8740: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
8750: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8760: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
8770: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
8780: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8790: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
87a0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
87b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
87c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
87d0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
87e0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
87f0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8800: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8810: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8820: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8830: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8840: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8850: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8860: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8880: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8890: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
88a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
88b0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
88c0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
88d0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
88e0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
88f0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8900: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8910: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
8920: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
8930: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
8940: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
8950: 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a  efined..** <ul>.
8960: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8970: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8980: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8990: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
89a0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
89b0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
89c0: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
89d0: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
89e0: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
89f0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8a00: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8a10: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8a20: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8a30: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8a40: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8a50: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8a60: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8a70: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8a80: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8a90: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8aa0: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8ab0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8ac0: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8ad0: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8ae0: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8af0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8b00: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8b10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8b20: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8b30: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8b40: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8b50: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8b60: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8b70: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8b80: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8b90: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8ba0: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8bb0: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8bc0: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8bd0: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8be0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8bf0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8c00: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8c10: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8c20: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8c30: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8c40: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8c50: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8c60: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
8c70: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
8c80: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
8c90: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
8ca0: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
8cb0: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
8cc0: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
8cd0: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
8ce0: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
8cf0: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
8d00: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
8d10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
8d20: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
8d30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8d40: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
8d50: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8d60: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
8d70: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
8d90: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
8da0: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
8db0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
8dc0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
8dd0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8de0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
8df0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
8e00: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
8e10: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
8e20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e30: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
8e40: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
8e50: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
8e60: 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TED] opcode is g
8e70: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
8e80: 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  lly by.** SQLite
8e90: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c   and sent to all
8ea0: 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20   VFSes in place 
8eb0: 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65  of a call to the
8ec0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a   xSync method.**
8ed0: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
8ee0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  se connection ha
8ef0: 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  s [PRAGMA synchr
8f00: 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46  onous] set to OF
8f10: 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65  F.)^.** Some spe
8f20: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e  cialized VFSes n
8f30: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
8f40: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72  in order to oper
8f50: 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a  ate correctly.**
8f60: 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79   when [PRAGMA sy
8f70: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
8f80: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
8f90: 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20  FF] is set, but 
8fa0: 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64  most .** VFSes d
8fb0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
8fc0: 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c  signal and shoul
8fd0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
8fe0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  e this opcode..*
8ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
9000: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9010: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9020: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9030: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64  s.** opcode as d
9040: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9050: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
9060: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9070: 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68  ized VFSes.** th
9080: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9090: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
90a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
90b0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
90c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
90d0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
90e0: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
90f0: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
9100: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
9110: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
9120: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9130: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9140: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
9150: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
9160: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
9170: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
9180: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
9190: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
91a0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
91b0: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
91c0: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
91d0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
91e0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
91f0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
9200: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
9210: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
9220: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9230: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9240: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
9250: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
9260: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
9270: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
9280: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
9290: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
92a0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
92b0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
92c0: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
92d0: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
92e0: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
92f0: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
9300: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
9310: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
9320: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9330: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9340: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9350: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
9360: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
9370: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
9380: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
9390: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
93a0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
93b0: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
93c0: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
93d0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
93e0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
93f0: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
9400: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
9410: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
9420: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
9430: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
9440: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
9450: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
9460: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
9470: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
9480: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
9490: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
94a0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
94b0: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
94c0: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
94d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
94e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
94f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9500: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
9510: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9520: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9530: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9540: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9550: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
9560: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
9570: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
9580: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
9590: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
95a0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
95b0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
95c0: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
95d0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
95e0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
95f0: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
9600: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
9610: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
9620: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9630: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
9640: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
9650: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
9660: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
9670: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
9680: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
9690: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
96a0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
96b0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
96c0: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
96d0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
96e0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
96f0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
9700: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
9710: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
9720: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
9730: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
9740: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9750: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
9760: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
9770: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
9780: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
9790: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
97a0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
97b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
97c0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
97d0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
97e0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
97f0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9800: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9810: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
9820: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
9830: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
9840: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
9850: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
9860: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
9870: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
9880: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
9890: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
98a0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
98b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
98c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
98d0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
98e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
98f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9900: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9910: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9920: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9930: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
9940: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
9950: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
9960: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
9970: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
9980: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
9990: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
99a0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
99b0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
99c0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
99d0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
99e0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
99f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9a00: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
9a10: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
9a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9a30: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
9a40: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
9a50: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
9a60: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
9a70: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
9a80: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
9a90: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
9aa0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
9ab0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
9ac0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
9ad0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
9ae0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
9af0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9b00: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
9b10: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9b20: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
9b30: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
9b40: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
9b50: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
9b60: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
9b70: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
9b80: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
9b90: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
9ba0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
9bb0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
9bc0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
9bd0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
9be0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
9bf0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
9c00: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
9c10: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
9c20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9c30: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
9c40: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9c50: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
9c60: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
9c70: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
9c80: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
9c90: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
9ca0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
9cb0: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
9cc0: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
9cd0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
9ce0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
9cf0: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
9d00: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
9d10: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
9d20: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
9d30: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
9d40: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
9d50: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
9d60: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
9d70: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
9d80: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9d90: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
9da0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
9db0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
9dc0: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
9dd0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
9de0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
9df0: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
9e00: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
9e10: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
9e20: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
9e30: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
9e40: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
9e50: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
9e60: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
9e70: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
9e80: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
9e90: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9ea0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
9eb0: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
9ec0: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
9ed0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
9ee0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
9ef0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9f00: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
9f10: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
9f20: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
9f30: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
9f40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9f50: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
9f60: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
9f70: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
9f80: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9f90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
9fa0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9fb0: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
9fc0: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
9fd0: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
9fe0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
9ff0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a000: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a010: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
a020: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
a030: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
a040: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
a050: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
a060: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
a070: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
a080: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
a090: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
a0a0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a0b0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
a0c0: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
a0d0: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
a0e0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
a0f0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
a100: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a110: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a120: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
a130: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
a140: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
a150: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
a160: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
a170: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
a180: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
a190: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
a1a0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
a1b0: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
a1c0: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
a1d0: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
a1e0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
a1f0: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
a200: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
a210: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
a220: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a230: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a240: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
a250: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
a260: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
a270: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
a280: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
a290: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a2a0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a2b0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a2c0: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
a2d0: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
a2e0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
a2f0: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
a300: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
a310: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
a320: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
a330: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
a340: 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74  tatement.  ^If t
a350: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a360: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a370: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
a380: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
a390: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
a3a0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
a3b0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
a3c0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
a3d0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
a3e0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
a3f0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
a400: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
a410: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
a420: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
a430: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
a440: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
a450: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a460: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a470: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
a480: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
a490: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
a4a0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
a4b0: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
a4c0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
a4d0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a4e0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
a4f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a500: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
a510: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a520: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a530: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a540: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a550: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a560: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a570: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a580: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a590: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a5a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a5b0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a5c0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a5d0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a5e0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a5f0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a600: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a610: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a620: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a630: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a640: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a650: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a660: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a670: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a680: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a690: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a6a0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a6b0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a6c0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a6d0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a6e0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a6f0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a700: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a710: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a720: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a730: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a740: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a750: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a760: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a770: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a780: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
a790: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
a7a0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
a7b0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
a7c0: 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 66 69 6c   invoke this fil
a7d0: 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20 68 61 76  e-control to hav
a7e0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
a7f0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
a800: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
a810: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
a820: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
a830: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
a840: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
a850: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
a860: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
a870: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
a880: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
a890: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
a8a0: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
a8b0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
a8c0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
a8d0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
a8e0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
a8f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a900: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
a910: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
a920: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
a930: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
a940: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
a950: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f  y leak..**.** </
a960: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
a970: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
a980: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
a990: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
a9a0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
a9b0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
a9c0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
a9d0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
a9e0: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
a9f0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
aa00: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
aa10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
aa20: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
aa30: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
aa40: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
aa50: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
aa60: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
aa70: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
aa80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aa90: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
aaa0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
aab0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
aac0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
aad0: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
aae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
aaf0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
ab00: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
ab10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ab20: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
ab30: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
ab40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ab50: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
ab60: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
ab70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ab80: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
ab90: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
aba0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
abb0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
abc0: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
abd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
abe0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
abf0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
ac00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
ac10: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
ac20: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
ac30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
ac40: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
ac50: 20 20 20 20 31 36 0a 0a 2f 2a 0a 2a 2a 20 43 41      16../*.** CA
ac60: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
ac70: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
ac80: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
ac90: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
aca0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
acb0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
acc0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
acd0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
ace0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
acf0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
ad00: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
ad10: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
ad20: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
ad30: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
ad40: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
ad50: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
ad60: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
ad70: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
ad80: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
ad90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
ada0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
adb0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
adc0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
add0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
ade0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
adf0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
ae00: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
ae10: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
ae20: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
ae30: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
ae40: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
ae50: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
ae60: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
ae70: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
ae80: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
ae90: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
aea0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
aeb0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
aec0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
aed0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
aee0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
aef0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
af00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
af10: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
af20: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
af30: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
af40: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
af50: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
af60: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
af70: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
af80: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
af90: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
afa0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
afb0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
afc0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
afd0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
afe0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
aff0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
b000: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
b010: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
b020: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
b030: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
b040: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
b050: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
b060: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
b070: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
b080: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
b090: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
b0a0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
b0b0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
b0c0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
b0d0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
b0e0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
b0f0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
b100: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
b110: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
b120: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
b130: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
b140: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
b150: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
b160: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
b170: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
b180: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b190: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
b1a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
b1b0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
b1c0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
b1d0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
b1e0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
b1f0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
b200: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
b210: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
b220: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
b230: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
b240: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
b250: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
b260: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
b270: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
b280: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
b290: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
b2a0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
b2b0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
b2c0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
b2d0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
b2e0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
b2f0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
b300: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
b310: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
b320: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
b330: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
b340: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
b350: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
b360: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
b370: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
b380: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
b390: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
b3a0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
b3b0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
b3c0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
b3d0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
b3e0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
b3f0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
b400: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
b410: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
b420: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
b430: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
b440: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
b450: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
b460: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
b470: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
b480: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
b490: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
b4a0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b4b0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
b4c0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
b4d0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
b4e0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
b4f0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
b500: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
b510: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
b520: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
b530: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
b540: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
b550: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
b560: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
b570: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
b580: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
b590: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
b5a0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
b5b0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
b5c0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
b5d0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
b5e0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
b5f0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
b600: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
b610: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
b620: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
b630: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
b640: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b650: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
b660: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
b670: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
b680: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
b690: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
b6a0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
b6b0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
b6c0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
b6d0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
b6e0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
b6f0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
b700: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
b710: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
b720: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
b730: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
b740: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
b750: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
b760: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
b770: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
b780: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
b790: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
b7a0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
b7b0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
b7c0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
b7d0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
b7e0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
b7f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
b800: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
b810: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
b820: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
b830: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
b840: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
b850: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
b860: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
b870: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
b880: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
b890: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
b8a0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
b8b0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
b8c0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
b8d0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
b8e0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
b8f0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
b900: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
b910: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
b920: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
b930: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b940: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b950: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
b960: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
b970: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
b980: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
b990: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b9a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b9b0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
b9c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
b9d0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
b9e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b9f0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
ba00: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ba10: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
ba20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ba30: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
ba40: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
ba50: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
ba60: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ba70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
ba80: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
ba90: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
baa0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
bab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
bac0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
bad0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
bae0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
baf0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
bb00: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
bb10: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
bb20: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
bb30: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
bb40: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
bb50: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
bb60: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
bb70: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
bb80: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
bb90: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
bba0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
bbb0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
bbc0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
bbd0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
bbe0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
bbf0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
bc00: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
bc10: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
bc20: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
bc30: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
bc40: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
bc50: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
bc60: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
bc70: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
bc80: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
bc90: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
bca0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
bcb0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
bcc0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
bcd0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
bce0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
bcf0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
bd00: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
bd10: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
bd20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
bd30: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
bd40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bd50: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
bd60: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
bd70: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
bd80: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
bd90: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
bda0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
bdb0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
bdc0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
bdd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
bde0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
bdf0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
be00: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
be10: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
be20: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
be30: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
be40: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
be50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
be60: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
be70: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
be80: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
be90: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
bea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
beb0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
bec0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
bed0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
bee0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
bef0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
bf00: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
bf10: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
bf20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
bf30: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
bf40: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
bf50: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
bf60: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
bf70: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
bf80: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
bf90: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
bfa0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
bfb0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
bfc0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
bfd0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
bfe0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
bff0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
c000: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
c010: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
c020: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
c030: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
c040: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
c050: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
c060: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
c070: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
c080: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
c090: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
c0a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
c0b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
c0c0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
c0d0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
c0e0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
c0f0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
c100: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
c110: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
c120: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
c130: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
c140: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
c150: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
c160: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
c170: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
c180: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
c190: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
c1a0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
c1b0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
c1c0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
c1d0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
c1e0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c1f0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
c200: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
c210: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
c220: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
c230: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
c240: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
c250: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
c260: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
c270: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
c280: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c290: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
c2a0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
c2b0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
c2c0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
c2d0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
c2e0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
c2f0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
c300: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
c310: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
c320: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
c330: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
c340: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
c350: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
c360: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
c370: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
c380: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
c390: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
c3a0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
c3b0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
c3c0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
c3d0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
c3e0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
c3f0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
c400: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
c410: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
c420: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
c430: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
c440: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
c450: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
c460: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
c470: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
c480: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
c490: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
c4a0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
c4b0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
c4c0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
c4d0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
c4e0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
c4f0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
c500: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
c510: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
c520: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
c530: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
c540: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
c550: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
c560: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
c570: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
c580: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
c590: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
c5a0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
c5b0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
c5c0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
c5d0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
c5e0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
c5f0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
c600: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
c610: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
c620: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
c630: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
c640: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
c650: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
c660: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
c670: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
c680: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
c690: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
c6a0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
c6b0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
c6c0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
c6d0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
c6e0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
c6f0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
c700: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
c710: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
c720: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
c730: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
c740: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
c750: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
c760: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
c770: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
c780: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
c790: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
c7a0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
c7b0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c7c0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
c7d0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
c7e0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
c7f0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
c800: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
c810: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
c820: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
c830: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
c840: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
c850: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
c860: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c870: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
c880: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
c890: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
c8a0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
c8b0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
c8c0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
c8d0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
c8e0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
c8f0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
c900: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
c910: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
c920: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
c930: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c940: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
c950: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
c960: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
c970: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
c980: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
c990: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
c9a0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
c9b0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
c9c0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
c9d0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
c9e0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
c9f0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
ca00: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
ca10: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
ca20: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
ca30: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
ca40: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
ca50: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
ca60: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
ca70: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
ca80: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
ca90: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
caa0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
cab0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
cac0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
cad0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
cae0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
caf0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
cb00: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
cb10: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
cb20: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
cb30: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
cb40: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
cb50: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
cb60: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
cb70: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
cb80: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
cb90: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
cba0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
cbb0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
cbc0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
cbd0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
cbe0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
cbf0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
cc00: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
cc10: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
cc20: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
cc30: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
cc40: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
cc50: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
cc60: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
cc70: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
cc80: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
cc90: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
cca0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
ccb0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
ccc0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
ccd0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
cce0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
ccf0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
cd00: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
cd10: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
cd20: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
cd30: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
cd40: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
cd50: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
cd60: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
cd70: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
cd80: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
cd90: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
cda0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
cdb0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
cdc0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
cdd0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
cde0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
cdf0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
ce00: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
ce10: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
ce20: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
ce30: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
ce40: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
ce50: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
ce60: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
ce70: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
ce80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ce90: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
cea0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
ceb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
cec0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
ced0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
cee0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
cef0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
cf00: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
cf10: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
cf20: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
cf30: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
cf40: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
cf50: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
cf60: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
cf70: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
cf80: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
cf90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
cfa0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
cfb0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
cfc0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
cfd0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cfe0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
cff0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
d000: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d010: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
d020: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
d030: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
d040: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
d050: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
d060: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
d070: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
d080: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
d090: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
d0a0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
d0b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
d0c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
d0d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
d0e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d0f0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
d100: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
d110: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
d120: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
d130: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
d140: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
d150: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
d160: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
d170: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
d180: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
d190: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d1a0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
d1b0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
d1c0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
d1d0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
d1e0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
d1f0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
d200: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
d210: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
d220: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
d230: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d240: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d250: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
d260: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d270: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
d280: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
d290: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
d2a0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
d2b0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
d2c0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
d2d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d2e0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d2f0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
d300: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
d310: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
d320: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
d330: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d340: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
d350: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
d360: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
d370: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d380: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
d390: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
d3a0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
d3b0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
d3c0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
d3d0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
d3e0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
d3f0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
d400: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
d410: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
d420: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
d430: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
d440: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
d450: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
d460: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
d470: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
d480: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
d490: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
d4a0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
d4b0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
d4c0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
d4d0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
d4e0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
d4f0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
d500: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
d510: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
d520: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
d530: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d540: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
d550: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d560: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
d570: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d580: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
d590: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
d5a0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
d5b0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d5c0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
d5d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
d5e0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
d5f0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
d600: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
d610: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d620: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
d630: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
d640: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
d650: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
d660: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
d670: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
d680: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
d690: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
d6a0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
d6b0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
d6c0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
d6d0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
d6e0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
d6f0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
d700: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
d710: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
d720: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d730: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
d740: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
d750: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
d760: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
d770: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
d780: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
d790: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
d7a0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
d7b0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
d7c0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
d7d0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
d7e0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
d7f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d800: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
d810: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d820: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
d830: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
d840: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
d850: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
d860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d870: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
d880: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
d890: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d8a0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
d8b0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
d8c0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
d8d0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d8e0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
d8f0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
d900: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
d910: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
d920: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
d930: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
d940: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
d950: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
d960: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
d970: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
d980: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
d990: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
d9a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
d9b0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
d9c0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
d9d0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d9e0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d9f0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
da00: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
da10: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
da20: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
da30: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
da40: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
da50: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
da60: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
da70: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
da80: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
da90: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
daa0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
dab0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
dac0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
dad0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
dae0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
daf0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
db00: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
db10: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
db20: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
db30: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
db40: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
db50: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
db60: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
db70: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
db80: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
db90: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
dba0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
dbb0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
dbc0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
dbd0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
dbe0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
dbf0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
dc00: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
dc10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
dc20: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
dc30: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
dc40: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
dc50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
dc60: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
dc70: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
dc80: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
dc90: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
dca0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
dcb0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
dcc0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
dcd0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
dce0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
dcf0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
dd00: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
dd10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
dd20: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
dd30: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
dd40: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
dd50: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
dd60: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
dd70: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dd80: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
dd90: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
dda0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
ddb0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
ddc0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
ddd0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
dde0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
ddf0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
de00: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
de10: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
de20: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
de30: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
de40: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
de50: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
de60: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
de70: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
de80: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
de90: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
dea0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
deb0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
dec0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
ded0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
dee0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
def0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
df00: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
df10: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
df20: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
df30: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
df40: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
df50: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
df60: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
df70: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
df80: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
df90: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
dfa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
dfb0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
dfc0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
dfd0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
dfe0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
dff0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
e000: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
e010: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
e020: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
e030: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
e040: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
e050: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
e060: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
e070: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e080: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
e090: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
e0a0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
e0b0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
e0c0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
e0d0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
e0e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
e0f0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
e100: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
e110: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e120: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
e130: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
e140: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
e150: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
e160: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
e170: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
e180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e190: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e1a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
e1b0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
e1c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
e1d0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
e1e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e1f0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
e200: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
e210: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
e220: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
e230: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
e240: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
e250: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
e260: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
e270: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
e280: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
e290: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
e2a0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
e2b0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
e2c0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
e2d0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
e2e0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
e2f0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
e300: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
e310: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
e320: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
e330: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
e340: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
e350: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e360: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e370: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
e380: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
e390: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
e3a0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
e3b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e3c0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
e3d0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
e3e0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
e3f0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
e400: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
e410: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
e420: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
e430: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
e440: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
e450: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
e460: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
e470: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e480: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
e490: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
e4a0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
e4b0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
e4c0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
e4d0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
e4e0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
e4f0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
e500: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e510: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
e520: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
e530: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
e540: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
e550: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
e560: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
e570: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
e580: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
e590: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
e5a0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
e5b0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
e5c0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
e5d0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
e5e0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
e5f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e600: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
e610: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
e620: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e630: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
e640: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
e650: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
e660: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
e670: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
e680: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
e690: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
e6a0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
e6b0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
e6c0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
e6d0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
e6e0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
e6f0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
e700: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
e710: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
e720: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
e730: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e740: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
e750: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
e760: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
e770: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
e780: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
e790: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
e7a0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
e7b0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
e7c0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
e7d0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
e7e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e7f0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
e800: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
e810: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
e820: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
e830: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
e840: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e850: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e860: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
e870: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
e880: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
e890: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
e8a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
e8b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
e8c0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
e8d0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
e8e0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
e8f0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
e900: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
e910: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
e920: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
e930: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
e940: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
e950: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
e960: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
e970: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
e980: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
e990: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
e9a0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
e9b0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
e9c0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
e9d0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
e9e0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
e9f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ea00: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
ea10: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ea20: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
ea30: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
ea40: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
ea50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
ea60: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
ea70: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
ea80: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
ea90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eaa0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
eab0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
eac0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ead0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
eae0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
eaf0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
eb00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
eb10: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
eb20: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
eb30: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
eb40: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
eb50: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
eb60: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
eb70: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
eb80: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
eb90: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
eba0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
ebb0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
ebc0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
ebd0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
ebe0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
ebf0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
ec00: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
ec10: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
ec20: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
ec30: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
ec40: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
ec50: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
ec60: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
ec70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ec80: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
ec90: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
eca0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
ecb0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
ecc0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
ecd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
ece0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
ecf0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
ed00: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
ed10: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
ed20: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
ed30: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
ed40: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
ed50: 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
ed60: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
ed70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
ed80: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
ed90: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
eda0: 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
edb0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
edc0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
edd0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
ede0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
edf0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
ee00: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
ee10: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
ee20: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
ee30: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ee40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
ee50: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
ee60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
ee70: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
ee80: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
ee90: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
eea0: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
eeb0: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
eec0: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
eed0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
eee0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
eef0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
ef00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
ef10: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
ef20: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
ef30: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
ef40: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
ef50: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
ef60: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
ef70: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
ef80: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
ef90: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
efa0: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
efb0: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
efc0: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
efd0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
efe0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
eff0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
f000: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
f010: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
f020: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
f030: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
f040: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
f050: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
f060: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
f070: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
f080: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
f090: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
f0a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
f0b0: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
f0c0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
f0d0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
f0e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f0f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
f100: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
f110: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
f120: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
f130: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
f140: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
f150: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
f160: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
f170: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
f180: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
f190: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
f1a0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
f1b0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
f1c0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
f1d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
f1e0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
f1f0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
f200: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
f210: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
f220: 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
f230: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
f240: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
f250: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
f260: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
f270: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
f280: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
f290: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
f2a0: 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
f2b0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
f2c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
f2d0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
f2e0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
f2f0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
f300: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
f310: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
f320: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
f330: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
f340: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
f350: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
f360: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
f370: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
f380: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
f390: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
f3a0: 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
f3b0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
f3c0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
f3d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f3e0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
f3f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f400: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f410: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
f420: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
f430: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
f440: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
f450: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
f460: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
f470: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
f480: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
f490: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f4a0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
f4b0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
f4c0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
f4d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f4e0: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
f4f0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
f500: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
f510: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f520: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
f530: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
f540: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
f550: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
f560: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
f570: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
f580: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
f590: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
f5a0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
f5b0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
f5c0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
f5d0: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
f5e0: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
f5f0: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
f600: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
f610: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
f620: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
f630: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
f640: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
f650: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
f660: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
f670: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
f680: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
f690: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
f6a0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
f6b0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
f6c0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
f6d0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
f6e0: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
f6f0: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
f700: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f710: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
f720: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
f730: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
f740: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
f750: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f760: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
f770: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
f780: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
f790: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
f7a0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
f7b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
f7c0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f7d0: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
f7e0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
f7f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
f800: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
f810: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
f820: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f830: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
f840: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f850: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
f860: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
f870: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f880: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
f890: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
f8a0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
f8b0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
f8c0: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
f8d0: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
f8e0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
f8f0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
f900: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
f910: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
f920: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
f930: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
f940: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
f950: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
f960: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
f970: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
f980: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
f990: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f9a0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
f9b0: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
f9c0: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
f9d0: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
f9e0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
f9f0: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
fa00: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
fa10: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
fa20: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
fa30: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
fa40: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
fa50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fa60: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
fa70: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
fa80: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
fa90: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
faa0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
fab0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
fac0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
fad0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
fae0: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
faf0: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
fb00: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
fb10: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
fb20: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
fb30: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
fb40: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
fb50: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
fb60: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
fb70: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
fb80: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
fb90: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
fba0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
fbb0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
fbc0: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
fbd0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
fbe0: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
fbf0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
fc00: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
fc10: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
fc20: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
fc30: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
fc40: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
fc50: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
fc60: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
fc70: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
fc80: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
fc90: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
fca0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
fcb0: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
fcc0: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
fcd0: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
fce0: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
fcf0: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
fd00: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
fd10: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
fd20: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
fd30: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
fd40: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
fd50: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
fd60: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
fd70: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
fd80: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
fd90: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
fda0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
fdb0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
fdc0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
fdd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
fde0: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
fdf0: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
fe00: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
fe10: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
fe20: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
fe30: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
fe40: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
fe50: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
fe60: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
fe70: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
fe80: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
fe90: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
fea0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
feb0: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
fec0: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
fed0: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
fee0: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
fef0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
ff00: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
ff10: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
ff20: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
ff30: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
ff40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
ff50: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
ff60: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
ff70: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
ff80: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
ff90: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
ffa0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
ffb0: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
ffc0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
ffd0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
ffe0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
fff0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
10000 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
10010 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
10020 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
10030 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
10040 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
10050 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
10060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
10070 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
10080 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
10090 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
100a0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
100b0 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
100c0 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
100d0 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
100e0 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
100f0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
10100 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
10110 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
10120 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
10130 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
10140 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10150 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
10160 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
10170 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
10180 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
10190 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
101a0 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
101b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
101c0 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
101d0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
101e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
101f0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
10200 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10210 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
10220 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
10230 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
10240 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
10250 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
10260 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
10270 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
10280 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
10290 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
102a0 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
102b0 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
102c0 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
102d0 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
102e0 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
102f0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
10300 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
10310 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
10320 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
10330 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
10340 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
10350 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
10360 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
10370 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
10380 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10390 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
103a0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
103b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
103c0 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
103d0 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
103e0 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
103f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
10400 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
10410 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
10420 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
10430 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
10440 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
10450 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
10460 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
10470 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
10480 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
10490 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
104a0 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
104b0 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
104c0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
104d0 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
104e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
104f0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
10500 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
10510 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
10520 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
10530 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
10540 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
10550 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10560 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
10570 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
10580 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
10590 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
105a0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
105b0 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
105c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
105d0 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
105e0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
105f0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
10600 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10610 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
10620 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
10630 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10640 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
10650 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
10660 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
10670 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
10680 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
10690 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
106a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
106b0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
106c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
106d0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
106e0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
106f0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10700 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10710 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10720 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
10730 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10740 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
10750 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
10760 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
10770 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
10780 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
10790 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
107a0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
107b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
107c0 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
107d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
107e0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
107f0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10800 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10810 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10820 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10830 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10840 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10850 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10860 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
10870 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
10880 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
10890 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
108a0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
108b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
108c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
108d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
108e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
108f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10900 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
10910 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
10920 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
10930 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
10940 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
10950 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
10960 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
10970 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
10980 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
10990 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
109a0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
109b0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
109c0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
109d0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
109e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
109f0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10a00 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
10a10 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
10a20 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
10a30 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
10a40 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
10a50 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
10a60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10a70 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
10a80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10a90 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
10aa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
10ab0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
10ac0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10ad0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
10ae0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10af0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
10b00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10b10 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
10b20 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10b30 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10b40 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10b50 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10b60 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10b70 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
10b80 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
10b90 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
10ba0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
10bb0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
10bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
10bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
10be0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
10bf0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10c00 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
10c10 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
10c20 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
10c30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10c40 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
10c50 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
10c60 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
10c70 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
10c80 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
10c90 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
10ca0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
10cb0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
10cc0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
10cd0 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
10ce0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
10cf0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
10d00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10d10 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
10d20 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
10d30 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10d40 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10d50 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10d60 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10d70 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10d80 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10d90 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
10da0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
10db0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
10dc0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
10dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10de0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
10df0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10e00 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10e10 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
10e20 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
10e30 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10e40 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
10e50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10e60 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
10e70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10e80 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
10e90 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
10ea0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
10eb0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
10ec0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
10ed0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
10ee0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
10ef0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
10f00 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
10f10 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
10f20 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
10f30 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
10f40 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
10f50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10f60 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
10f70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
10f80 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
10f90 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
10fa0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
10fb0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
10fc0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
10fd0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10fe0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
10ff0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
11000 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
11010 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
11020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11030 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
11040 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
11050 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
11060 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
11070 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
11080 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11090 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
110a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
110b0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
110c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
110d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
110e0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
110f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11100 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11110 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11120 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11130 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11140 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11150 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11160 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
11170 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
11180 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
11190 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
111a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
111b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
111c0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
111d0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
111e0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
111f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11200 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11220 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
11230 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
11240 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
11250 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
11260 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11270 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
11280 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
11290 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
112a0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
112b0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
112c0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
112d0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
112e0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
112f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11300 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
11310 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
11320 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
11330 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11340 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
11350 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
11360 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
11370 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
11380 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
11390 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
113a0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
113b0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
113c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
113d0 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
113e0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
113f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11400 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
11410 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11420 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
11430 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
11440 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
11450 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
11460 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
11470 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
11480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
11490 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
114a0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
114b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
114c0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
114d0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
114e0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
114f0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11500 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
11510 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
11520 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
11530 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
11540 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
11550 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
11560 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
11570 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
11580 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
11590 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
115a0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
115b0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
115c0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
115d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
115e0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
115f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11600 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
11610 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11620 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
11630 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
11640 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
11650 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
11660 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
11670 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
11680 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
11690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
116a0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
116b0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
116c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
116d0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
116e0 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
116f0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
11700 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
11710 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
11720 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
11730 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
11740 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
11750 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
11760 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
11770 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11780 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
11790 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
117a0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
117b0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
117c0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
117d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
117e0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
117f0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
11800 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
11810 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
11820 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
11830 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
11840 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
11850 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
11860 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
11870 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11880 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
11890 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
118a0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
118b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
118c0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
118d0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
118e0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
118f0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11900 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
11910 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
11920 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
11930 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11940 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
11950 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
11960 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
11970 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
11980 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
11990 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
119a0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
119b0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
119c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
119d0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
119e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
119f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11a00 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
11a10 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
11a20 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
11a30 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
11a40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11a50 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
11a60 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
11a70 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
11a80 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
11a90 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
11aa0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11ab0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
11ac0 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
11ad0 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
11ae0 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
11af0 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
11b00 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
11b10 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11b20 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
11b30 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11b40 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
11b50 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
11b60 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
11b70 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
11b80 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
11b90 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
11ba0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
11bb0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
11bc0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
11bd0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
11be0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
11bf0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
11c00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11c10 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
11c20 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
11c30 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
11c40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11c50 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
11c60 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
11c70 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11c80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11c90 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
11ca0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
11cb0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
11cc0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
11cd0 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
11ce0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
11cf0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
11d00 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11d10 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
11d20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
11d30 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
11d40 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
11d50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
11d60 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
11d70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
11d80 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
11d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
11da0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
11db0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11dc0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11dd0 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
11de0 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
11df0 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
11e00 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
11e10 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
11e20 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
11e30 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
11e40 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
11e50 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
11e60 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
11e70 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
11e80 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
11e90 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
11ea0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
11eb0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
11ec0 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
11ed0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
11ee0 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
11ef0 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
11f00 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
11f10 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
11f20 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
11f30 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
11f40 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
11f50 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
11f60 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
11f70 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
11f80 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
11f90 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
11fa0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
11fb0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
11fc0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
11fd0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
11fe0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
11ff0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
12000 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12010 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
12020 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
12030 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
12040 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
12050 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
12060 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
12070 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
12080 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
12090 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
120a0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
120b0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
120c0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
120d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
120e0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
120f0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
12100 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
12110 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12120 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
12130 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
12140 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
12150 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
12160 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
12170 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
12180 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
12190 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
121a0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
121b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
121c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
121d0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
121e0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
121f0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
12200 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
12210 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
12220 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
12230 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12240 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
12250 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
12260 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
12270 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
12280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
12290 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
122a0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
122b0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
122c0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
122d0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
122e0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
122f0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
12300 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
12310 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
12320 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
12330 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
12340 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
12350 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
12360 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
12370 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
12380 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
12390 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
123a0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
123b0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
123c0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
123d0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
123e0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
123f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12400 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
12410 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
12420 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
12430 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
12440 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
12450 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
12460 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
12470 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
12480 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
12490 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
124a0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
124b0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
124c0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
124d0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
124e0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
124f0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
12500 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
12510 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
12520 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
12530 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
12540 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
12550 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
12560 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
12570 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12580 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
12590 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
125a0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
125b0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
125c0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
125d0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
125e0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
125f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12600 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
12610 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
12620 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12630 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12640 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12650 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12660 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
12670 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12680 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
12690 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
126a0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
126b0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
126c0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
126d0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
126e0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
126f0 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
12700 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
12710 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12720 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
12730 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
12740 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12750 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
12760 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12770 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
12780 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12790 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
127a0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
127b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
127c0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
127d0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
127e0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
127f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12800 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
12810 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
12820 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
12830 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
12840 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
12850 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
12860 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
12870 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12880 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
12890 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
128a0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
128b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
128c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
128d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
128e0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
128f0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
12900 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12910 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12920 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12930 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12940 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
12950 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12960 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
12970 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12980 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
12990 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
129a0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
129b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
129c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
129d0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
129e0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
129f0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12a00 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12a10 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
12a20 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12a30 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12a40 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
12a50 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
12a60 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
12a70 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
12a80 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
12a90 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
12aa0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12ab0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12ac0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12ad0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12ae0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12af0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12b00 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12b10 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12b20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12b30 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12b40 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
12b50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12b60 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
12b70 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
12b80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12b90 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
12ba0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12bb0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
12bc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
12bd0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
12be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12bf0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12c00 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12c10 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12c20 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12c30 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
12c40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12c50 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
12c60 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
12c70 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
12c80 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12c90 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
12ca0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
12cb0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
12cc0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
12cd0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
12ce0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
12cf0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
12d00 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
12d10 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
12d20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
12d30 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
12d40 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
12d50 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
12d60 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
12d70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12d80 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
12d90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
12da0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
12db0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
12dc0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
12dd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
12de0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
12df0 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
12e00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12e10 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
12e20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12e30 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
12e40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12e50 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12e60 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12e70 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12e80 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
12e90 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
12ea0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
12eb0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
12ec0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
12ed0 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
12ee0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
12ef0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
12f00 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12f10 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
12f20 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
12f30 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
12f40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12f50 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12f70 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
12f80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12f90 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
12fa0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12fb0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12fc0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12fd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12fe0 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
12ff0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13000 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
13010 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
13020 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
13030 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13040 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
13050 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
13060 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13070 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
13080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
13090 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
130a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
130b0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
130c0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
130d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
130e0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
130f0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
13100 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
13110 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
13120 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
13130 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
13140 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
13150 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
13160 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
13170 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
13180 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
13190 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
131a0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
131b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
131c0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
131d0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
131e0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
131f0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
13200 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
13210 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
13220 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
13230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13240 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
13250 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
13260 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13270 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
13280 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
13290 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
132a0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
132b0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
132c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
132d0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
132e0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
132f0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
13300 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13310 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
13320 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
13330 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
13340 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
13350 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
13360 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
13370 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
13380 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
13390 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
133a0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
133b0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
133c0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
133d0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
133e0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
133f0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
13400 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
13410 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
13420 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
13430 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
13440 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
13450 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
13460 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
13470 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
13480 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
13490 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
134a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
134b0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
134c0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
134d0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
134e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
134f0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
13500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13510 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
13520 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13530 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13540 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
13550 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
13560 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
13570 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
13580 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
13590 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
135a0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
135b0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
135c0 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
135d0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
135e0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
135f0 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
13600 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
13610 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
13620 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
13630 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
13640 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
13650 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
13660 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
13670 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
13680 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
13690 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
136a0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
136b0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
136c0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
136d0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
136e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
136f0 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
13700 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13710 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
13720 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
13730 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
13740 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
13750 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
13760 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
13770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
13780 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
13790 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
137a0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
137b0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
137c0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
137d0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
137e0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
137f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
13800 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
13810 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
13820 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
13830 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
13840 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13850 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
13860 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
13870 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
13880 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
13890 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69  ger argument whi
138a0 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
138b0 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61  d as.** a boolea
138c0 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
138d0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
138e0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
138f0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a  ing indices for.
13900 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  ** full table sc
13910 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
13920 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65   optimizer.  The
13930 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
13940 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a   is determined.*
13950 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  * by the [SQLITE
13960 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f  _ALLOW_COVERING_
13970 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70  INDEX_SCAN] comp
13980 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
13990 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69   or is "on".** i
139a0 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74  f that compile-t
139b0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d  ime option is om
139c0 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62  itted..** The ab
139d0 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65  ility to disable
139e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
139f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
13a00 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
13a10 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20  s.** is because 
13a20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79  some incorrectly
13a30 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70   coded legacy ap
13a40 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74  plications might
13a50 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20   malfunction.** 
13a60 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  malfunction when
13a70 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
13a80 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
13a90 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
13aa0 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
13ab0 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
13ac0 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
13ad0 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
13ae0 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
13af0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
13b00 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
13b10 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
13b20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
13b30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13b40 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
13b50 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13b60 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
13b70 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13b80 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
13b90 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
13ba0 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
13bb0 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
13bc0 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
13bd0 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
13be0 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
13bf0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
13c00 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
13c10 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
13c20 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
13c30 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  l>.**.** [[SQLIT
13c40 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
13c50 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
13c60 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
13c70 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
13c80 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
13c90 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
13ca0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
13cb0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42  e.** SQLITE_ENAB
13cc0 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65 2d 70 72  LE_SQLLOG pre-pr
13cd0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
13ce0 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
13cf0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
13d00 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
13d10 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
13d20 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
13d30 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
13d40 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
13d50 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
13d60 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
13d70 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
13d80 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
13d90 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
13da0 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
13db0 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
13dc0 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
13dd0 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
13de0 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
13df0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
13e00 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
13e10 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
13e20 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
13e30 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
13e40 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
13e50 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
13e60 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
13e70 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
13e80 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
13e90 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
13ea0 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
13eb0 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
13ec0 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
13ed0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
13ee0 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
13ef0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
13f00 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
13f10 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
13f20 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
13f30 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
13f40 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
13f50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
13f60 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
13f70 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
13f80 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
13f90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
13fa0 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
13fb0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
13fc0 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
13fd0 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
13fe0 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  e..** </dl>.*/.#
13ff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14000 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
14010 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
14020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14030 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
14040 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
14050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14060 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14070 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
14080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14090 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
140a0 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
140b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
140c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
140d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
140e0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
140f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14100 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
14110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
14120 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
14130 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
14140 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
14150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14160 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
14170 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
14180 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
141a0 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
141b0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
141c0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
141d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
141e0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
141f0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
14200 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
14210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14220 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
14230 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14240 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
14250 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14260 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
14270 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
14280 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
14290 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
142a0 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
142b0 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
142c0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
142d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
142e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
142f0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
14300 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
14310 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14320 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
14330 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
14340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14350 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
14360 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
14370 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14380 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
14390 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
143a0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
143b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
143c0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
143d0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
143e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
143f0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
14400 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
14410 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
14420 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14430 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
14440 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
14450 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
14460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14470 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
14480 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
14490 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
144a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
144b0 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
144c0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
144d0 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  id* */../*.** CA
144e0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
144f0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
14500 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
14510 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
14520 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
14530 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
14540 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
14550 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
14560 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
14570 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
14580 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
14590 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
145a0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
145b0 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
145c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
145d0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
145e0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
145f0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
14600 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
14610 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
14620 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
14630 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
14640 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
14650 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
14660 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
14670 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
14680 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
14690 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
146a0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
146b0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
146c0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
146d0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
146e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
146f0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
14700 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
14710 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14720 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
14730 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
14740 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
14750 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
14760 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
14770 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
14780 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
14790 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
147a0 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
147b0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
147c0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
147d0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
147e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
147f0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
14800 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14810 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
14820 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
14830 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
14840 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
14850 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
14860 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
14870 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
14880 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
14890 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
148a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
148b0 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
148c0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
148d0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
148e0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
148f0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
14900 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
14910 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
14920 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
14930 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
14940 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
14950 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
14960 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
14970 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14980 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
14990 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
149a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
149b0 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
149c0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
149d0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
149e0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
149f0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
14a00 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
14a10 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
14a20 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
14a30 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
14a40 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
14a50 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
14a60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
14a70 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
14a80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
14a90 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
14aa0 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
14ab0 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
14ac0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
14ad0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
14ae0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
14af0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14b00 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
14b10 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
14b20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
14b30 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
14b40 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
14b50 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
14b60 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
14b70 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
14b80 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
14b90 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
14ba0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
14bb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
14bc0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
14bd0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
14be0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
14bf0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
14c00 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
14c10 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
14c20 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
14c30 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
14c40 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
14c50 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
14c60 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
14c70 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
14c80 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
14c90 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
14ca0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
14cb0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
14cc0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
14cd0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
14ce0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
14cf0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
14d00 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
14d10 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
14d20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
14d30 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
14d40 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
14d50 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
14d60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14d70 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
14d80 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
14d90 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
14da0 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
14db0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
14dc0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
14dd0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
14de0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
14df0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
14e00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14e10 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
14e20 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
14e30 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
14e40 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
14e50 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
14e60 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
14e70 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
14e80 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
14e90 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
14ea0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
14eb0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
14ec0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
14ed0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
14ee0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
14ef0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
14f00 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
14f10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
14f20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
14f30 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
14f40 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
14f50 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
14f60 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
14f70 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
14f80 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
14f90 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
14fa0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
14fb0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
14fc0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
14fd0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
14fe0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
14ff0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
15000 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
15010 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
15020 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
15030 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
15040 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
15050 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15060 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
15070 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
15080 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
15090 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
150a0 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
150b0 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
150c0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
150d0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
150e0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
150f0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
15100 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
15110 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
15120 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
15130 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
15140 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
15150 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
15160 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15170 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
15180 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
15190 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
151a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
151b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
151c0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
151d0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
151e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
151f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
15200 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
15210 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
15220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15230 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
15240 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
15250 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
15260 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
15270 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
15280 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
15290 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
152a0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
152b0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
152c0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
152d0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
152e0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
152f0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
15300 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
15310 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
15320 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
15330 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
15340 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
15350 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
15360 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
15370 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
15380 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
15390 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
153a0 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
153b0 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
153c0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
153d0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
153e0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
153f0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
15400 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
15410 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
15420 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
15430 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
15440 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
15450 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
15460 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
15470 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
15480 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
15490 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
154a0 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
154b0 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
154c0 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
154d0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
154e0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
154f0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
15500 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
15510 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
15520 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
15530 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
15540 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
15550 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
15560 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
15570 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
15580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15590 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
155a0 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20   argument.  ^As 
155b0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
155c0 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f  n 3.7.7, this ro
155d0 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64  utines.** record
155e0 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
155f0 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20  t rowid of both 
15600 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20  ordinary tables 
15610 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62  and [virtual tab
15620 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  les]..** ^If no 
15630 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
15640 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
15650 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
15660 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
15670 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
15680 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
15690 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
156a0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
156b0 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
156c0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
156d0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
156e0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
156f0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
15700 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
15710 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
15720 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
15730 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
15740 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
15750 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
15760 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
15770 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
15780 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
15790 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
157a0 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
157b0 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
157c0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
157d0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
157e0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
157f0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
15800 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
15810 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
15820 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
15830 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
15840 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
15850 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
15860 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
15870 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
15880 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
15890 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
158a0 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
158b0 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
158c0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
158d0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
158e0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
158f0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
15900 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
15910 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
15920 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
15930 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
15940 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
15950 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
15960 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
15970 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
15980 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
15990 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
159a0 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
159b0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
159c0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
159d0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
159e0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
159f0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
15a00 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
15a10 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
15a20 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
15a30 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
15a40 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
15a50 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
15a60 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
15a70 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
15a80 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
15a90 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
15aa0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
15ab0 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
15ac0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
15ad0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
15ae0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
15af0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
15b00 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
15b10 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
15b20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
15b30 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
15b40 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
15b50 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
15b60 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
15b70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15b80 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
15b90 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
15ba0 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
15bb0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
15bc0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
15bd0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
15be0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
15bf0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
15c00 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
15c10 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
15c20 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
15c30 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
15c40 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
15c50 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
15c60 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
15c70 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
15c80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
15c90 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
15ca0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
15cb0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
15cc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15cd0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
15ce0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
15cf0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
15d00 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
15d10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
15d20 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
15d30 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
15d40 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
15d50 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
15d60 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
15d70 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
15d80 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
15d90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15da0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
15db0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
15dc0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
15dd0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
15de0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
15df0 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
15e00 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
15e10 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
15e20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
15e30 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
15e40 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
15e50 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
15e60 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
15e70 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
15e80 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
15e90 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15ea0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
15eb0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
15ec0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
15ed0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
15ee0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
15ef0 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
15f00 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
15f10 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
15f20 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
15f30 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
15f40 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
15f50 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
15f60 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
15f70 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
15f80 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
15f90 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
15fa0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
15fb0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
15fc0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
15fd0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
15fe0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
15ff0 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
16000 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
16010 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
16020 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
16030 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
16040 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
16050 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
16060 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
16070 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
16080 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
16090 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
160a0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
160b0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
160c0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
160d0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
160e0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
160f0 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
16100 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
16110 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
16120 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
16130 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
16140 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
16150 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
16160 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
16170 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
16180 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
16190 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
161a0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
161b0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
161c0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
161d0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
161e0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
161f0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
16200 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
16210 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
16220 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
16230 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
16240 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
16250 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
16260 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
16270 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
16280 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
16290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
162a0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
162b0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
162c0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
162d0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
162e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
162f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16300 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
16310 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
16320 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
16330 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
16340 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
16350 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
16360 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
16370 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
16380 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
16390 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
163a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
163b0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
163c0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
163d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
163e0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
163f0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
16400 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
16410 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
16420 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
16430 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
16440 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
16450 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
16460 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
16470 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
16480 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
16490 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
164a0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
164b0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
164c0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
164d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
164e0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
164f0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
16500 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
16510 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
16520 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
16530 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
16540 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
16550 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
16560 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
16570 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
16580 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
16590 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
165a0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
165b0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
165c0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
165d0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
165e0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
165f0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
16600 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
16610 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
16620 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
16630 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
16640 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
16650 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
16660 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
16670 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
16680 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
16690 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
166a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
166b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
166c0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
166d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
166e0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
166f0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
16700 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16710 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
16720 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
16730 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
16740 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
16750 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
16760 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
16770 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
16780 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
16790 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
167a0 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
167b0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
167c0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
167d0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
167e0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
167f0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
16800 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
16810 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
16820 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
16830 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
16840 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
16850 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
16860 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
16870 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
16880 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
16890 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
168a0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
168b0 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
168c0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
168d0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
168e0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
168f0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
16900 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
16910 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
16920 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
16930 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
16940 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
16950 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
16960 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
16970 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
16980 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
16990 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
169a0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
169b0 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
169c0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
169d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
169e0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
169f0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
16a00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
16a10 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
16a20 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
16a30 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
16a40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
16a50 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
16a60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
16a70 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
16a80 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
16a90 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
16aa0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
16ab0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
16ac0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
16ad0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
16ae0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
16af0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
16b00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16b10 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
16b20 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16b30 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
16b40 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
16b50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
16b60 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
16b70 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
16b80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
16b90 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
16ba0 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
16bb0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
16bc0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
16bd0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
16be0 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
16bf0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
16c00 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
16c10 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
16c20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
16c30 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
16c40 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
16c50 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
16c60 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
16c70 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
16c80 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
16c90 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
16ca0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
16cb0 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
16cc0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
16cd0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
16ce0 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
16cf0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
16d00 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
16d10 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
16d20 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
16d30 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
16d40 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
16d50 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
16d60 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
16d70 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
16d80 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
16d90 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
16da0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
16db0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
16dc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
16dd0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
16de0 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
16df0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
16e00 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
16e10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
16e20 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
16e30 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
16e40 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
16e50 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
16e60 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
16e70 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
16e80 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
16e90 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
16ea0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
16eb0 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
16ec0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
16ed0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
16ee0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
16ef0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
16f00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
16f10 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
16f20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
16f30 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
16f40 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
16f50 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
16f60 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
16f70 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
16f80 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
16f90 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
16fa0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
16fb0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
16fc0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
16fd0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
16fe0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16ff0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
17000 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
17010 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
17020 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
17030 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
17040 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
17050 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
17060 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
17070 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
17080 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
17090 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
170a0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
170b0 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
170c0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
170d0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
170e0 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
170f0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
17100 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
17110 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
17120 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
17130 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
17140 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
17150 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
17160 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
17170 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
17180 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
17190 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
171a0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
171b0 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
171c0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
171d0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
171e0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
171f0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
17200 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
17210 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
17220 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
17230 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
17240 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17250 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17260 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17270 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
17280 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
17290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
172a0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
172b0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
172c0 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
172d0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
172e0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
172f0 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
17300 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
17310 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
17320 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
17330 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
17340 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
17350 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
17360 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
17370 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
17380 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
17390 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
173a0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
173b0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
173c0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
173d0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
173e0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
173f0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
17400 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
17410 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
17420 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
17430 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
17440 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
17450 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
17460 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
17470 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
17480 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
17490 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
174a0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
174b0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
174c0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
174d0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
174e0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
174f0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
17500 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
17510 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
17520 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
17530 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
17540 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
17550 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
17560 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
17570 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
17580 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
17590 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
175a0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
175b0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
175c0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
175d0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
175e0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
175f0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
17600 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
17610 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
17620 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
17630 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
17640 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
17650 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
17660 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
17670 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
17680 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
17690 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
176a0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
176b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
176c0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
176d0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
176e0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
176f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
17700 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
17710 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
17720 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
17730 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
17740 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
17750 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
17760 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
17770 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
17780 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
17790 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
177a0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
177b0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
177c0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
177d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
177e0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
177f0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
17800 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
17810 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
17820 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
17830 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
17840 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
17850 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
17860 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
17870 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
17880 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
17890 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
178a0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
178b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
178c0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
178d0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
178e0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
178f0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
17900 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
17910 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
17920 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
17930 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
17940 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
17950 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
17960 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
17970 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17980 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
17990 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
179a0 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
179b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
179c0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
179d0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
179e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
179f0 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
17a00 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
17a10 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
17a20 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
17a30 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
17a40 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
17a50 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
17a60 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
17a70 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
17a80 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
17a90 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
17aa0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
17ab0 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
17ac0 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
17ad0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
17ae0 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
17af0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
17b00 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
17b10 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
17b20 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
17b30 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
17b40 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
17b50 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
17b60 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
17b70 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
17b80 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
17b90 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
17ba0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
17bb0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
17bc0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
17bd0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
17be0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
17bf0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
17c00 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
17c10 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
17c20 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
17c30 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
17c40 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
17c50 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17c60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
17c70 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
17c80 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
17c90 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
17ca0 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
17cb0 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
17cc0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
17cd0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
17ce0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
17cf0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
17d00 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
17d10 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
17d20 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
17d30 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
17d40 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17d50 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
17d60 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
17d70 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
17d80 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
17d90 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
17da0 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
17db0 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
17dc0 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
17dd0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
17de0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
17df0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
17e00 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
17e10 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
17e20 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
17e30 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
17e40 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
17e50 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
17e60 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
17e70 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
17e80 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
17e90 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
17ea0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
17eb0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
17ec0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
17ed0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
17ee0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
17ef0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
17f00 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
17f10 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
17f20 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
17f30 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
17f40 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
17f50 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
17f60 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
17f70 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
17f80 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
17f90 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
17fa0 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
17fb0 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
17fc0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
17fd0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
17fe0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
17ff0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
18000 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
18010 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
18020 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
18030 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
18040 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
18050 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
18060 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
18070 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
18080 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
18090 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
180a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
180b0 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
180c0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
180d0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
180e0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
180f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
18100 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
18110 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
18120 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
18130 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
18140 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
18150 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
18160 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
18170 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
18180 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
18190 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
181a0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
181b0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
181c0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
181d0 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
181e0 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
181f0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
18200 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
18210 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
18220 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
18230 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
18240 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
18250 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
18260 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
18270 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
18280 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
18290 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
182a0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
182b0 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
182c0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
182d0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
182e0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
182f0 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
18300 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
18310 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
18320 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
18330 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
18340 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
18350 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
18360 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
18370 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
18380 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
18390 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
183a0 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
183b0 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
183c0 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
183d0 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
183e0 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
183f0 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
18400 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
18410 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
18420 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
18430 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
18440 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
18450 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
18460 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
18470 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
18480 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
18490 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
184a0 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
184b0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
184c0 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
184d0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
184e0 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
184f0 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
18500 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
18510 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
18520 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
18530 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
18540 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
18550 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
18560 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18570 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
18580 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
18590 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
185a0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
185b0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
185c0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
185d0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
185e0 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
185f0 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
18600 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
18610 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
18620 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
18630 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
18640 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
18650 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
18660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18670 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
18680 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
18690 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
186a0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
186b0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
186c0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
186d0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
186e0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
186f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
18700 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
18710 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
18720 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
18730 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
18740 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
18750 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18760 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
18770 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
18780 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
18790 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
187a0 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
187b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
187c0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
187d0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
187e0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
187f0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
18800 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
18810 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
18820 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
18830 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
18840 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
18850 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
18860 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
18870 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
18880 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
18890 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
188a0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
188b0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
188c0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
188d0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
188e0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
188f0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
18900 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
18910 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
18920 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
18930 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
18940 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
18950 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
18960 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
18970 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
18980 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
18990 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
189a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
189b0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
189c0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
189d0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
189e0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
189f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
18a00 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
18a10 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
18a20 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
18a30 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
18a40 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
18a50 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
18a60 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
18a70 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
18a80 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
18a90 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
18aa0 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
18ab0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
18ac0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
18ad0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
18ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
18af0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
18b00 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
18b10 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
18b20 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
18b30 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
18b40 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
18b50 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
18b60 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
18b70 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
18b80 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
18b90 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
18ba0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
18bb0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
18bc0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
18bd0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
18be0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
18bf0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
18c00 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
18c10 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
18c20 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
18c30 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
18c40 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
18c50 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
18c60 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
18c70 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
18c80 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
18c90 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
18ca0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
18cb0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
18cc0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
18cd0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
18ce0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
18cf0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
18d00 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
18d10 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
18d20 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
18d30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
18d40 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
18d50 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
18d60 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
18d70 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
18d80 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
18d90 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
18da0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
18db0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
18dc0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
18dd0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
18de0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
18df0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
18e00 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
18e10 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
18e20 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
18e30 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
18e40 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
18e50 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
18e60 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
18e70 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
18e80 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
18e90 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
18ea0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
18eb0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
18ec0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
18ed0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
18ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
18ef0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
18f00 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
18f10 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
18f20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
18f30 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
18f40 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
18f50 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
18f60 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
18f70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
18f80 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
18f90 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
18fa0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
18fb0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
18fc0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
18fd0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
18fe0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
18ff0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
19000 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
19010 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
19020 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
19030 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
19040 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
19050 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
19060 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19070 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
19080 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
19090 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
190a0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
190b0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
190c0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
190d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
190e0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
190f0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
19100 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
19110 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
19120 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
19130 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
19140 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
19150 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
19160 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
19170 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
19180 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
19190 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
191a0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
191b0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
191c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
191d0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
191e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
191f0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
19200 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
19210 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
19220 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
19230 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19240 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
19250 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19260 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
19270 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19280 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
19290 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
192a0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
192b0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
192c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
192d0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
192e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
192f0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
19300 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19310 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
19320 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
19330 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
19340 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
19350 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
19360 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
19370 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
19380 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
19390 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
193a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
193b0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
193c0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
193d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
193e0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
193f0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
19400 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
19410 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
19420 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
19430 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
19440 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
19450 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
19460 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
19470 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
19480 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
19490 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
194a0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
194b0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
194c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
194d0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
194e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
194f0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
19500 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
19510 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
19520 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
19530 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
19540 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
19550 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
19560 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
19570 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
19580 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
19590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
195a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
195b0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
195c0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
195d0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
195e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
195f0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
19600 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
19610 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
19620 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
19630 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
19640 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
19650 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
19660 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
19670 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
19680 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
19690 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
196a0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
196b0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
196c0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
196d0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
196e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
196f0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
19700 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
19710 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19720 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
19730 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
19740 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
19750 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19760 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19770 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
19780 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
19790 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
197a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
197b0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
197c0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
197d0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
197e0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
197f0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
19800 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
19810 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
19820 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
19830 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
19840 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
19850 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
19860 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
19870 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
19880 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
19890 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
198a0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
198b0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
198c0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
198d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
198e0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
198f0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
19900 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
19910 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
19920 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
19930 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
19940 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
19950 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
19960 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
19970 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
19980 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
19990 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
199a0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
199b0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
199c0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
199d0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
199e0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
199f0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
19a00 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
19a10 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
19a20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
19a30 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
19a40 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
19a50 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
19a60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
19a70 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
19a80 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
19a90 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
19aa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19ab0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
19ac0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
19ad0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
19ae0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
19af0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
19b00 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
19b10 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
19b20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
19b30 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
19b40 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
19b50 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
19b60 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
19b70 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
19b80 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
19b90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19ba0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
19bb0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
19bc0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19bd0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
19be0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
19bf0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
19c00 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
19c10 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
19c20 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
19c30 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
19c40 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
19c50 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
19c60 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
19c70 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
19c80 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
19c90 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
19ca0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
19cb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
19cc0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
19cd0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
19ce0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
19cf0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
19d00 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
19d10 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
19d20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
19d30 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
19d40 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
19d50 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
19d60 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
19d70 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
19d80 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
19d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
19da0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
19db0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
19dc0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
19dd0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
19de0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
19df0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
19e00 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
19e10 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
19e20 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
19e30 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
19e40 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
19e50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
19e60 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
19e70 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
19e80 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
19e90 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
19ea0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
19eb0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
19ec0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
19ed0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
19ee0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
19ef0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
19f00 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
19f10 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
19f20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
19f30 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
19f40 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
19f50 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
19f60 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
19f70 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19f80 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
19f90 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
19fa0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
19fb0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
19fc0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
19fd0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
19fe0 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
19ff0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1a000 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1a010 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1a020 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1a030 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1a040 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1a050 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1a060 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1a070 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1a080 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1a090 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1a0a0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1a0b0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1a0c0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1a0d0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1a0e0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1a0f0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1a100 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1a110 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1a120 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1a130 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1a140 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1a150 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1a160 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1a170 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1a180 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1a190 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1a1a0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1a1b0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1a1c0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1a1d0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1a1e0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1a1f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1a200 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1a210 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1a220 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1a230 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1a240 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1a250 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1a260 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1a270 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a280 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a290 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1a2a0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1a2b0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1a2c0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1a2d0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1a2e0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1a2f0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1a300 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1a310 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1a320 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1a330 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1a340 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1a350 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1a360 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1a370 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1a380 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1a390 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1a3a0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1a3b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a3c0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1a3d0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1a3e0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1a3f0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1a400 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a410 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1a420 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1a430 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1a440 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1a450 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1a460 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1a470 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1a480 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a490 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1a4a0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1a4b0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1a4c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a4d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1a4e0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1a4f0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1a500 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1a510 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1a520 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1a530 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1a540 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1a550 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1a560 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1a570 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1a580 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1a590 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1a5a0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1a5b0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1a5c0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1a5d0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1a5e0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1a5f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1a600 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1a610 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1a620 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1a630 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1a640 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1a650 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1a660 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1a670 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1a680 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1a690 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a6a0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1a6b0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1a6c0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1a6d0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1a6e0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1a6f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1a700 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1a710 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1a720 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1a730 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a740 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1a750 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1a760 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1a770 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1a780 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1a790 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1a7a0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1a7b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1a7c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1a7d0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1a7e0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1a7f0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1a800 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1a810 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1a820 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1a830 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1a840 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1a850 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1a860 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1a870 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1a880 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  */.SQLITE_API ch
1a890 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1a8a0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1a8b0 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1a8c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1a8d0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1a8e0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53  ar*, va_list);.S
1a8f0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1a900 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1a910 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1a920 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1a930 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1a940 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1a950 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1a960 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1a970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a980 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1a990 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1a9a0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1a9b0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1a9c0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1a9d0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1a9e0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1a9f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1aa00 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1aa10 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1aa20 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1aa30 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1aa40 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1aa50 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1aa60 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1aa70 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1aa80 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1aa90 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1aaa0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1aab0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1aac0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1aad0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1aae0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1aaf0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1ab00 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1ab10 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1ab20 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1ab30 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1ab40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1ab50 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1ab60 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1ab70 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1ab80 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1ab90 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1aba0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1abb0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1abc0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1abd0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1abe0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1abf0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1ac00 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1ac10 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1ac20 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1ac30 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1ac40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1ac50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ac60 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1ac70 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1ac80 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1ac90 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1aca0 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1acb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1acc0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1acd0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1ace0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1acf0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1ad00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1ad10 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1ad20 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1ad30 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1ad40 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1ad50 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1ad60 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1ad70 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1ad80 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1ad90 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1ada0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1adb0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1adc0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1add0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1ade0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1adf0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1ae00 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1ae10 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1ae20 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1ae30 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1ae40 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1ae50 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1ae60 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1ae70 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1ae80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1ae90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1aea0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
1aeb0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1aec0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1aed0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1aee0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1aef0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1af00 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1af10 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1af20 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1af30 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
1af40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1af50 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
1af60 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1af70 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
1af80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1af90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1afa0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
1afb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1afc0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1afd0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1afe0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1aff0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
1b000 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1b010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1b020 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1b030 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
1b040 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1b050 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b060 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1b070 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1b080 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1b090 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1b0a0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1b0b0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
1b0c0 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
1b0d0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1b0e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b0f0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1b100 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1b110 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1b120 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b130 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1b140 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1b150 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
1b160 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1b170 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
1b180 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1b190 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1b1a0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1b1b0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1b1c0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1b1d0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1b1e0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1b1f0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1b200 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1b210 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b220 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
1b230 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1b240 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1b250 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1b260 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
1b270 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
1b280 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
1b290 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1b2a0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1b2b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1b2c0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
1b2d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1b2e0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1b2f0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1b300 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1b310 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1b320 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1b330 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1b340 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1b350 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1b360 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1b370 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1b380 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1b390 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1b3a0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1b3b0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1b3c0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1b3d0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1b3e0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1b3f0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1b400 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1b410 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1b420 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1b430 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1b440 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1b450 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1b460 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1b470 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1b480 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1b490 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1b4a0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1b4b0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1b4c0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1b4d0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1b4e0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1b4f0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1b500 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1b510 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1b520 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1b530 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1b540 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1b550 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1b560 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1b570 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1b580 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1b590 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1b5a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1b5b0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1b5c0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1b5d0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1b5e0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1b5f0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1b600 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1b610 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1b620 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1b630 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1b640 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1b650 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1b660 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1b670 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1b680 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1b690 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1b6a0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1b6b0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1b6c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b6d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1b6e0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1b6f0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1b700 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1b710 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1b720 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1b730 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1b740 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1b750 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1b760 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1b770 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1b780 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1b790 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1b7a0 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oc()]..*/.SQLITE
1b7b0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1b7c0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1b7d0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1b7e0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1b7f0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51  (void*, int);.SQ
1b800 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1b810 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1b820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b830 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1b840 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1b850 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1b860 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1b870 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1b880 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1b890 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1b8a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b8b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1b8c0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1b8d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1b8e0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1b8f0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1b900 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1b910 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1b920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1b930 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1b940 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1b950 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1b960 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1b970 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1b980 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1b990 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1b9a0 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1b9b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1b9c0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1b9d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1b9e0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1b9f0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1ba00 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1ba10 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1ba20 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1ba30 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1ba40 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1ba50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ba60 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1ba70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ba80 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1ba90 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1baa0 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1bab0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1bac0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1bad0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1bae0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1baf0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1bb00 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1bb10 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1bb20 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1bb30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1bb40 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1bb50 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1bb60 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1bb70 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1bb80 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1bb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1bba0 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1bbb0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1bbc0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1bbd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1bbe0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1bbf0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1bc00 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1bc10 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1bc20 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1bc30 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1bc40 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1bc50 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53   the reset..*/.S
1bc60 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1bc70 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1bc80 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1bc90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
1bca0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1bcb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1bcc0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1bcd0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1bce0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1bcf0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1bd00 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1bd10 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1bd20 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1bd30 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1bd40 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1bd50 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1bd60 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1bd70 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1bd80 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1bd90 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1bda0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1bdb0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1bdc0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1bdd0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1bde0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1bdf0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1be00 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1be10 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1be20 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1be30 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1be40 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1be50 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1be60 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1be70 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1be80 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1be90 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1bea0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1beb0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1bec0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
1bed0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
1bee0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
1bef0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
1bf00 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
1bf10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
1bf20 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1bf30 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1bf40 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
1bf50 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1bf60 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1bf70 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1bf80 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1bf90 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
1bfa0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
1bfb0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
1bfc0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1bfd0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1bfe0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1bff0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1c000 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1c010 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1c020 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ethod..*/.SQLITE
1c030 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1c040 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1c050 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1c060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1c070 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1c080 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1c090 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
1c0a0 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1c0b0 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1c0c0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1c0d0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1c0e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c0f0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1c100 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1c110 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1c120 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c130 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1c140 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1c150 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1c160 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1c170 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1c180 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1c190 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c1a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1c1b0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1c1c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c1d0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1c1e0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1c1f0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1c200 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1c210 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1c220 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1c230 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1c240 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1c250 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c260 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1c270 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1c280 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1c290 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1c2a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1c2b0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1c2c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1c2d0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1c2e0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1c2f0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1c300 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1c310 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1c320 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1c330 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1c340 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1c350 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1c360 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1c370 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1c380 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1c390 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1c3a0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1c3b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c3c0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1c3d0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1c3e0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1c3f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1c400 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1c410 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1c420 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c430 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1c440 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1c450 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1c460 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1c470 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1c480 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1c490 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1c4a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1c4b0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1c4c0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1c4d0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1c4e0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1c4f0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1c500 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1c510 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c520 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1c530 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1c540 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1c550 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1c560 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1c570 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1c580 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1c590 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1c5a0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1c5b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1c5c0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1c5d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1c5e0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1c5f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1c600 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1c610 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1c620 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1c630 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1c640 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1c650 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1c660 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1c670 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1c680 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1c690 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1c6a0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1c6b0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1c6c0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1c6d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1c6e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1c6f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c700 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1c710 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1c720 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1c730 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1c740 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1c750 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1c760 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1c770 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1c780 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1c790 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1c7a0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1c7b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1c7c0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1c7d0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1c7e0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1c7f0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1c800 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1c810 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1c820 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1c830 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1c840 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1c850 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1c860 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1c870 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1c880 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1c890 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1c8a0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1c8b0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1c8c0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1c8d0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1c8e0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1c8f0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1c900 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1c910 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1c920 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1c930 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1c940 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1c950 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1c960 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1c970 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1c980 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1c990 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1c9a0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1c9b0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1c9c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1c9d0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1c9e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1c9f0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1ca00 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1ca10 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1ca20 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1ca30 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1ca40 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1ca50 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1ca60 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1ca70 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1ca80 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1ca90 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1caa0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1cab0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1cac0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1cad0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1cae0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1caf0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1cb00 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1cb10 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1cb20 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1cb30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1cb40 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1cb50 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1cb60 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1cb70 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1cb80 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1cb90 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1cba0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1cbb0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1cbc0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1cbd0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1cbe0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1cbf0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1cc00 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1cc10 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1cc20 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1cc30 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1cc40 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1cc50 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1cc60 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1cc70 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1cc80 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1cc90 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1cca0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1ccb0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1ccc0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1ccd0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1cce0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1ccf0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1cd00 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1cd10 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1cd20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1cd30 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1cd40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1cd50 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1cd60 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1cd70 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1cd80 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1cd90 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1cda0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1cdb0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1cdc0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1cdd0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1cde0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1cdf0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1ce00 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1ce10 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1ce20 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1ce30 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1ce40 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1ce50 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1ce60 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1ce70 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1ce80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1ce90 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1cea0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ceb0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1cec0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ced0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1cee0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1cef0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1cf00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cf10 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1cf20 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1cf30 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1cf40 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1cf50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cf60 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1cf70 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1cf80 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1cf90 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1cfa0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1cfb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1cfc0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1cfd0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1cfe0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1cff0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1d000 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1d010 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1d020 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1d030 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1d040 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1d050 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1d060 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1d070 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d080 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1d090 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1d0a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d0b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1d0c0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1d0d0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1d0e0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1d0f0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1d100 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1d110 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1d120 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1d130 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1d140 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1d150 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1d160 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1d170 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1d180 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1d190 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1d1a0 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  hange..*/.SQLITE
1d1b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1d1c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d1d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1d1e0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1d1f0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1d200 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1d210 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1d220 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1d230 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1d240 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1d250 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1d260 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1d270 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1d280 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1d290 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1d2a0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1d2b0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1d2c0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1d2d0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1d2e0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1d2f0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1d300 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1d310 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1d320 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1d330 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1d340 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d350 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1d360 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1d370 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1d380 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1d390 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1d3a0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1d3b0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1d3c0 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1d3d0 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1d3e0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1d3f0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1d400 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1d410 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d420 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1d430 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1d440 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1d450 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1d460 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1d470 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1d480 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1d490 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1d4a0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1d4b0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1d4c0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1d4d0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1d4e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1d4f0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1d500 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1d510 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1d520 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1d530 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1d540 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1d550 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1d560 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1d570 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1d580 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1d590 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1d5a0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1d5b0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1d5c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1d5d0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1d5e0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1d5f0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1d600 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d610 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1d620 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1d630 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1d640 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1d650 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1d660 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1d670 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1d680 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1d690 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1d6a0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1d6b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1d6c0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1d6d0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1d6e0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1d6f0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1d700 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1d710 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1d720 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1d730 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1d740 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d750 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1d760 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1d770 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1d780 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1d790 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1d7a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to 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 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1d7d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1d7e0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1d7f0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1d800 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1d810 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1d820 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1d830 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1d840 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1d850 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1d860 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1d870 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d880 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d890 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1d8a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1d8b0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1d8c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d8d0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1d8e0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1d8f0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1d900 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1d910 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d920 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1d930 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1d940 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1d950 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d960 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1d970 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1d980 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1d990 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1d9a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1d9b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1d9c0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1d9d0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1d9e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1d9f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1da00 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1da10 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1da20 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1da30 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1da40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1da50 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1da60 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1da70 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1da80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1da90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1daa0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1dab0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1dac0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1dad0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1dae0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1daf0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1db00 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1db10 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1db20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1db30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1db40 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1db50 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1db60 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1db70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1db80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1db90 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1dba0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1dbb0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1dbc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dbd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dbe0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1dbf0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1dc00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dc10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1dc20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dc30 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1dc40 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1dc50 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1dc60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1dc70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dc80 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1dc90 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1dca0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1dcb0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1dcc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dcd0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1dce0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1dcf0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1dd00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1dd10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1dd20 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1dd30 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1dd40 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1dd50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1dd60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1dd70 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1dd80 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1dd90 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1dda0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ddb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ddc0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1ddd0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1dde0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1ddf0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1de00 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1de10 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1de20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1de30 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1de40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1de50 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1de60 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1de70 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1de80 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1de90 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1dea0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1deb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1dec0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1ded0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1dee0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1def0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1df00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1df10 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1df20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1df30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1df40 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1df50 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1df60 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1df70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1df80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1df90 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1dfa0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1dfb0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1dfc0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1dfd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1dfe0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1dff0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1e000 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1e010 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e020 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e030 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1e040 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1e050 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1e060 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e070 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e080 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1e090 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1e0a0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1e0b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e0c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e0d0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1e0e0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1e0f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1e100 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e110 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e120 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1e130 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1e140 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e150 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e160 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e170 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1e180 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1e190 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1e1a0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1e1b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e1c0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1e1d0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1e1e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1e1f0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1e200 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1e210 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1e220 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1e230 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1e240 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1e250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1e260 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1e270 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1e280 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1e290 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1e2a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1e2b0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1e2c0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1e2d0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1e2e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1e2f0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1e300 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1e310 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e320 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1e330 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1e340 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1e350 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1e360 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1e370 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1e380 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1e390 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1e3a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1e3b0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1e3c0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1e3d0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1e3e0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1e3f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1e400 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1e410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1e420 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1e430 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1e440 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1e450 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1e460 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1e470 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1e480 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1e490 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1e4a0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1e4b0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1e4c0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1e4d0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1e4e0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1e4f0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1e500 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1e510 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1e520 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1e530 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1e540 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1e550 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1e560 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  .)^.**.** ^The c
1e570 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1e580 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1e590 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1e5a0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1e5b0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1e5c0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1e5d0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1e5e0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
1e5f0 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
1e600 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
1e610 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
1e620 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1e630 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
1e640 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
1e650 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
1e660 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1e670 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
1e680 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
1e690 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
1e6a0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
1e6b0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
1e6c0 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
1e6d0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
1e6e0 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
1e6f0 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
1e700 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
1e710 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
1e720 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
1e730 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1e740 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
1e750 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
1e760 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
1e770 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
1e780 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
1e790 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
1e7a0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
1e7b0 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1e7c0 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
1e7d0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
1e7e0 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
1e7f0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
1e800 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1e810 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1e820 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1e830 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1e840 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1e850 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
1e860 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1e870 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1e880 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1e890 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1e8a0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1e8b0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1e8c0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1e8d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e8e0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1e8f0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1e900 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1e910 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1e920 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1e930 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1e940 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1e950 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1e960 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1e970 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1e980 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1e990 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1e9a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e9b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1e9c0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1e9d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e9e0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1e9f0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1ea00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1ea10 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1ea20 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1ea30 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1ea40 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1ea50 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1ea60 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1ea70 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1ea80 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1ea90 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1eaa0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1eab0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1eac0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1ead0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1eae0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1eaf0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1eb00 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1eb10 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1eb20 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20  llback X..**.** 
1eb30 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1eb40 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1eb50 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1eb60 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1eb70 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1eb80 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1eb90 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1eba0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1ebb0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1ebc0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1ebd0 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1ebe0 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1ebf0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1ec00 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1ec10 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1ec20 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1ec30 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1ec40 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1ec50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1ec60 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1ec70 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1ec80 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1ec90 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1eca0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1ecb0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1ecc0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1ecd0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1ece0 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1ecf0 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1ed00 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1ed10 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1ed20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1ed30 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1ed40 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1ed50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ed60 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1ed70 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1ed80 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1ed90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eda0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1edb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1edc0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1edd0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1ede0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1edf0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1ee00 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1ee10 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49  raph..**.*/.SQLI
1ee20 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1ee30 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1ee40 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1ee50 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1ee60 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1ee70 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1ee80 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1ee90 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1eea0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1eeb0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1eec0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1eed0 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
1eee0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
1eef0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1ef00 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1ef10 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1ef20 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1ef30 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1ef40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1ef50 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1ef60 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1ef70 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1ef80 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1ef90 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1efa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1efb0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1efc0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1efd0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1efe0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1eff0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1f000 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1f010 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1f020 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1f030 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1f040 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1f050 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1f060 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1f070 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1f080 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
1f090 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
1f0a0 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
1f0b0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1f0c0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1f0d0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1f0e0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1f0f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1f100 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1f110 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1f120 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1f130 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
1f140 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1f150 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1f160 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1f170 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1f180 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1f190 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1f1a0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1f1b0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
1f1c0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
1f1d0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1f1e0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
1f1f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
1f200 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1f210 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1f220 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1f230 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1f240 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1f250 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1f260 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1f270 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1f280 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1f290 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1f2a0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1f2b0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1f2c0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1f2d0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1f2e0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1f2f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1f300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f310 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1f320 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1f330 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1f340 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1f350 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1f360 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1f370 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1f380 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f390 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1f3a0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1f3b0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1f3c0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1f3d0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1f3e0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1f3f0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1f400 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1f410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f420 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
1f430 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
1f440 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
1f450 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
1f460 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1f470 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1f480 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1f490 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1f4a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f4b0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1f4c0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1f4d0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1f4e0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
1f4f0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1f500 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
1f510 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1f520 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
1f530 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1f540 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1f550 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
1f560 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1f570 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
1f580 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
1f590 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
1f5a0 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
1f5b0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
1f5c0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1f5d0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1f5e0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1f5f0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1f600 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1f610 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1f620 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1f630 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1f640 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1f650 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1f660 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1f670 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1f680 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1f690 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1f6a0 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1f6b0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1f6c0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1f6d0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1f6e0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1f6f0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1f700 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1f710 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1f720 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1f730 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1f740 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1f750 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1f760 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1f770 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
1f780 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1f790 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1f7a0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1f7b0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1f7c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1f7d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1f7e0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
1f7f0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
1f800 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1f810 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1f820 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
1f830 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
1f840 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1f850 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
1f860 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
1f870 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
1f880 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
1f890 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
1f8a0 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
1f8b0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1f8c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1f8d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1f8e0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1f8f0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1f900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f910 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1f920 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1f930 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1f940 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1f950 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1f960 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1f970 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1f980 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1f990 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1f9a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f9b0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1f9c0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1f9d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f9e0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1f9f0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1fa00 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1fa10 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1fa20 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1fa30 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1fa40 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1fa50 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1fa60 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1fa70 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1fa80 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1fa90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1faa0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1fab0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1fac0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1fad0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1fae0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1faf0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1fb00 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1fb10 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1fb20 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1fb30 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1fb40 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1fb50 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1fb60 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1fb70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1fb80 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1fb90 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1fba0 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1fbb0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1fbc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
1fbd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1fbe0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1fbf0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1fc00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1fc10 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1fc20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1fc30 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1fc40 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1fc50 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1fc60 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1fc70 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
1fc80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1fc90 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1fca0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1fcb0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1fcc0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1fcd0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
1fce0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1fcf0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1fd00 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1fd10 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1fd20 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1fd30 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1fd40 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1fd50 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1fd60 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1fd70 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1fd80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1fd90 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1fda0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1fdb0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1fdc0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1fdd0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1fde0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1fdf0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1fe00 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1fe10 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1fe20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1fe30 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1fe40 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1fe50 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1fe60 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1fe70 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1fe80 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1fe90 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1fea0 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1feb0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1fec0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1fed0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1fee0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1fef0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1ff00 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1ff10 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1ff20 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1ff30 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1ff40 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1ff50 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1ff60 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1ff70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ff80 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1ff90 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1ffa0 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
1ffb0 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
1ffc0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
1ffd0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
1ffe0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
1fff0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
20000 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
20010 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
20020 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
20030 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
20040 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
20050 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
20060 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
20070 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
20080 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
20090 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
200a0 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
200b0 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
200c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
200d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
200e0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
200f0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
20100 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
20110 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
20120 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
20130 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20140 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
20150 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
20160 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
20170 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
20180 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
20190 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
201a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
201b0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
201c0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
201d0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
201e0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
201f0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
20200 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
20210 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
20220 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
20230 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
20240 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
20250 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
20260 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
20270 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
20280 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
20290 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
202a0 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
202b0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
202c0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
202d0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
202e0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
202f0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
20300 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
20310 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
20320 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
20330 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
20340 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
20350 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
20360 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
20370 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
20380 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
20390 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
203a0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
203b0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
203c0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
203d0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
203e0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
203f0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
20400 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
20410 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
20420 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
20430 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
20440 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
20450 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
20460 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
20470 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
20480 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
20490 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
204a0 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
204b0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
204c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
204d0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
204e0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
204f0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
20500 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
20510 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
20520 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
20530 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
20540 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
20550 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
20560 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
20570 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
20580 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
20590 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
205a0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
205b0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
205c0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
205d0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
205e0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
205f0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
20600 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
20610 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
20620 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
20630 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
20640 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
20650 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
20660 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
20670 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
20680 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
20690 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
206a0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
206b0 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
206c0 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
206d0 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
206e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
206f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
20700 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
20710 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
20720 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
20730 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
20740 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
20750 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
20760 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
20770 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
20780 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
20790 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
207a0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
207b0 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
207c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
207d0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
207e0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
207f0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
20800 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
20810 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
20820 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
20830 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
20840 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
20850 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
20860 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20870 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
20880 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
20890 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
208a0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
208b0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
208c0 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
208d0 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
208e0 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
208f0 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
20900 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
20910 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
20920 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
20930 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
20940 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
20950 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20960 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
20970 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
20980 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
20990 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
209a0 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
209b0 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
209c0 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
209d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
209e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
209f0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
20a00 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
20a10 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
20a20 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20a30 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
20a40 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
20a50 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
20a60 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
20a70 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
20a80 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
20a90 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
20aa0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
20ab0 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
20ac0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
20ad0 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
20ae0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
20af0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
20b00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
20b10 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
20b20 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
20b30 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
20b40 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
20b50 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
20b60 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
20b70 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
20b80 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
20b90 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
20ba0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
20bb0 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
20bc0 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
20bd0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
20be0 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
20bf0 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
20c00 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
20c10 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
20c20 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
20c30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
20c40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
20c50 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
20c60 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
20c70 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
20c80 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
20c90 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
20ca0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
20cb0 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
20cc0 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
20cd0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
20ce0 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
20cf0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20d00 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
20d10 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
20d20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
20d30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20d40 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
20d50 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
20d60 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
20d70 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
20d80 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
20d90 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
20da0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
20db0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
20dc0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
20dd0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
20de0 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
20df0 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
20e00 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
20e10 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
20e20 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
20e30 61 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64  aviour requested
20e40 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
20e50 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
20e60 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
20e70 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
20e80 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20  DCACHE flag..** 
20e90 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
20ea0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
20eb0 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
20ec0 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
20ed0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
20ee0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
20ef0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
20f00 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
20f10 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
20f20 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
20f30 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
20f40 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
20f50 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
20f60 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
20f70 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
20f80 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
20f90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
20fa0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
20fb0 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
20fc0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
20fd0 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
20fe0 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
20ff0 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
21000 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
21010 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
21020 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
21030 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21040 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
21050 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
21060 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
21070 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
21080 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
21090 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
210a0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
210b0 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
210c0 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
210d0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
210e0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
210f0 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
21100 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
21110 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
21120 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
21130 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
21140 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21150 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
21160 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
21170 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21180 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
21190 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
211a0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
211b0 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
211c0 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
211d0 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
211e0 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
211f0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
21200 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
21210 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
21220 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
21230 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
21240 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
21250 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
21260 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
21270 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
21280 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
21290 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
212a0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
212b0 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
212c0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
212d0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
212e0 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
212f0 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
21300 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
21310 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
21320 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
21330 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
21340 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
21350 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
21360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
21370 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
21380 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
21390 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
213a0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
213b0 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
213c0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
213d0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
213e0 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
213f0 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
21400 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
21410 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
21420 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
21430 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
21440 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
21450 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20  nolock <td>.**  
21460 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21470 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
21480 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
21490 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
214a0 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74  x-nolock"..** <t
214b0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
214c0 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
214d0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
214e0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
214f0 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
21500 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
21510 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
21520 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
21530 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
21540 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21550 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
21560 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
21570 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
21580 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
21590 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
215a0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
215b0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
215c0 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
215d0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
215e0 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
215f0 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
21600 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
21610 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
21620 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
21630 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
21640 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
21650 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
21660 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
21670 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
21680 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
21690 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
216a0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
216b0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
216c0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
216d0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
216e0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
216f0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
21700 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
21710 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
21720 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
21730 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
21740 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
21750 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
21760 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
21770 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
21780 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
21790 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
217a0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
217b0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
217c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
217d0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
217e0 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
217f0 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
21800 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
21810 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
21820 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
21830 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
21840 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
21850 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
21860 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
21870 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
21880 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
21890 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
218a0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
218b0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
218c0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
218d0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
218e0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
218f0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
21900 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
21910 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
21920 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
21930 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
21940 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
21950 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
21960 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
21970 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
21980 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21990 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
219a0 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ory].*/.SQLITE_A
219b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
219c0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
219d0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
219e0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
219f0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
21a00 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
21a10 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
21a20 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
21a30 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
21a40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
21a50 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
21a60 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
21a70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
21a80 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
21a90 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
21aa0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
21ab0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
21ac0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
21ad0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
21ae0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
21af0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
21b00 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
21b10 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
21b20 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
21b30 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
21b40 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
21b50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
21b60 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
21b70 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
21b80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
21b90 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
21ba0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
21bb0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
21bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
21bd0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
21be0 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
21bf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
21c00 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
21c10 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
21c20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
21c30 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
21c40 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
21c50 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
21c60 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
21c70 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
21c80 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
21c90 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
21ca0 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
21cb0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
21cc0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
21cd0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
21ce0 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
21cf0 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
21d00 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
21d10 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
21d20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
21d30 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
21d40 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
21d50 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
21d60 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
21d70 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
21d80 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
21d90 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
21da0 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
21db0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
21dc0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
21dd0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
21de0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
21df0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
21e00 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
21e10 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
21e20 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
21e30 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
21e40 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
21e50 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
21e60 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
21e70 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
21e80 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
21e90 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
21ea0 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
21eb0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
21ec0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
21ed0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
21ee0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
21ef0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21f00 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
21f10 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
21f20 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
21f30 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
21f40 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
21f50 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
21f60 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
21f70 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
21f80 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
21f90 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
21fa0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
21fb0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
21fc0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
21fd0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
21fe0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
21ff0 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
22000 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
22010 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
22020 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
22030 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
22040 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
22050 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22060 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
22070 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
22080 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
22090 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
220a0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
220b0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
220c0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
220d0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
220e0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
220f0 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
22100 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
22110 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
22120 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
22130 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
22140 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
22150 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
22160 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
22170 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22180 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
22190 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
221a0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
221b0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
221c0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
221d0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
221e0 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
221f0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
22200 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
22210 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
22220 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
22230 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
22240 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
22250 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
22260 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
22270 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
22280 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
22290 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
222a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
222b0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
222c0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
222d0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
222e0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
222f0 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
22300 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
22310 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
22320 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
22330 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
22340 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
22350 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
22360 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
22370 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
22380 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
22390 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
223a0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
223b0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
223c0 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
223d0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
223e0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
223f0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
22400 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
22410 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
22420 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
22430 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22440 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
22450 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
22460 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
22470 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f  efault);.SQLITE_
22480 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
22490 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
224a0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
224b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
224c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
224d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
224e0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
224f0 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
22500 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
22510 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
22520 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
22530 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
22540 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
22550 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
22560 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
22570 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
22580 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
22590 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
225a0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
225b0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
225c0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
225d0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
225e0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
225f0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
22600 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
22610 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
22620 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
22630 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
22640 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
22650 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
22660 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
22670 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
22680 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
22690 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
226a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
226b0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
226c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
226d0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
226e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
226f0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
22700 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
22710 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
22720 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
22730 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
22740 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
22750 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
22760 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
22770 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
22780 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
22790 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
227a0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
227b0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
227c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
227d0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
227e0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
227f0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
22800 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
22810 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
22820 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
22830 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
22840 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
22850 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
22860 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
22870 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
22880 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
22890 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
228a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
228b0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
228c0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
228d0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
228e0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
228f0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
22900 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
22910 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
22920 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
22930 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
22940 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
22950 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
22960 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
22970 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
22980 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
22990 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
229a0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
229b0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
229c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
229d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
229e0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
229f0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
22a00 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
22a10 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
22a20 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
22a30 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
22a40 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
22a50 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
22a60 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
22a70 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
22a80 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
22a90 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
22aa0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
22ab0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
22ac0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
22ad0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
22ae0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
22af0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
22b00 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
22b10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
22b20 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
22b30 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
22b40 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
22b50 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
22b60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
22b70 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
22b80 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
22b90 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
22ba0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
22bb0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
22bc0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
22bd0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
22be0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
22bf0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
22c00 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
22c10 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
22c20 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
22c30 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
22c40 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
22c50 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
22c60 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
22c70 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
22c80 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
22c90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
22ca0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
22cb0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
22cc0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
22cd0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
22ce0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
22cf0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
22d00 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22d10 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
22d20 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
22d30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
22d40 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
22d50 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
22d60 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
22d70 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
22d80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22d90 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
22da0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
22db0 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
22dc0 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
22dd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
22de0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
22df0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
22e00 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
22e10 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
22e20 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
22e30 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
22e40 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
22e50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
22e60 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
22e70 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
22e80 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
22e90 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
22ea0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
22eb0 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
22ec0 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
22ed0 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
22ee0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
22ef0 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
22f00 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22f10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22f20 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
22f30 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
22f40 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
22f50 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
22f60 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
22f70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
22f80 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
22f90 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
22fa0 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
22fb0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
22fc0 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
22fd0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
22fe0 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
22ff0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
23000 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
23010 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
23020 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
23030 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
23040 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
23050 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
23060 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
23070 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
23080 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
23090 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
230a0 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
230b0 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
230c0 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
230d0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
230e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
230f0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
23100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
23110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23120 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
23130 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
23140 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
23150 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
23160 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
23170 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
23180 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
23190 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
231a0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
231b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
231c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
231d0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
231e0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
231f0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
23200 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
23210 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
23220 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
23230 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
23240 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
23250 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
23260 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
23270 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
23280 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
23290 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
232a0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
232b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
232c0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
232d0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
232e0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
232f0 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
23300 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
23310 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
23320 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
23330 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
23340 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
23350 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
23360 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
23370 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
23380 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
23390 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
233a0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
233b0 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
233c0 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
233d0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
233e0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
233f0 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
23400 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
23410 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
23420 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
23430 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
23440 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
23450 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
23460 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
23470 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
23480 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
23490 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
234a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
234b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
234c0 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
234d0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
234e0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
234f0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
23500 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
23510 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
23520 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
23530 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
23540 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
23550 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
23560 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
23570 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
23580 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
23590 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
235a0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
235b0 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
235c0 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
235d0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
235e0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
235f0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
23600 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
23610 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
23620 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
23630 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
23640 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
23650 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
23660 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
23670 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
23680 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
23690 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
236a0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
236b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
236c0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
236d0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
236e0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
236f0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
23700 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
23710 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
23720 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
23730 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
23740 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
23750 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
23760 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
23770 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
23780 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
23790 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
237a0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
237b0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
237c0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
237d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
237e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
237f0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
23800 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
23810 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
23820 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
23830 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
23840 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
23850 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
23860 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
23870 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
23880 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
23890 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
238a0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
238b0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
238c0 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c  releases..*/.SQL
238d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
238e0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
238f0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
23900 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
23910 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
23920 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
23930 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
23940 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
23950 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
23960 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
23970 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
23980 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
23990 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
239a0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
239b0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
239c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
239d0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
239e0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
239f0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
23a00 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
23a10 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
23a20 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
23a30 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
23a40 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
23a50 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
23a60 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
23a70 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
23a80 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
23a90 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23aa0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
23ab0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
23ac0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
23ad0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
23ae0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
23af0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
23b00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
23b10 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
23b20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
23b30 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
23b40 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23b50 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
23b60 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
23b70 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
23b80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
23b90 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
23ba0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
23bb0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
23bc0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
23bd0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
23be0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
23bf0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
23c00 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
23c10 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
23c20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23c30 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
23c40 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
23c50 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
23c60 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
23c70 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
23c80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
23c90 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
23ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
23cb0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
23cc0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23cd0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
23ce0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
23cf0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
23d00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23d10 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
23d20 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
23d30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
23d40 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
23d50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23d60 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
23d70 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
23d80 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
23d90 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
23da0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23db0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
23dc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
23dd0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
23de0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
23df0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
23e00 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
23e10 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
23e20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
23e30 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
23e40 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
23e50 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
23e60 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
23e70 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
23e80 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
23e90 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
23ea0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
23eb0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23ec0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
23ed0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
23ee0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23ef0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
23f00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
23f10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
23f20 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
23f30 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
23f40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23f50 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
23f60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
23f70 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
23f80 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23f90 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
23fa0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
23fb0 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
23fc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
23fd0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
23fe0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
23ff0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24000 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24010 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
24020 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24030 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
24040 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
24050 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
24060 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
24070 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
24080 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24090 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
240a0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
240b0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
240c0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
240d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
240e0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
240f0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
24100 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
24110 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
24120 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
24130 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
24140 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24150 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
24160 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24170 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
24180 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
24190 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
241a0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
241b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
241c0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
241d0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
241e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
241f0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
24200 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
24210 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24220 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
24230 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
24240 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24250 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
24260 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
24270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24280 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
24290 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
242a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
242b0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
242c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
242d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
242e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
242f0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
24300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24310 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
24320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24330 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
24340 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
24350 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
24360 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
24370 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
24380 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
24390 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
243a0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
243b0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
243c0 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
243d0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
243e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
243f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
24400 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
24410 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
24420 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
24430 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
24440 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
24450 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
24460 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
24470 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
24480 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
24490 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
244a0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
244b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
244c0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
244d0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
244e0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
244f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
24500 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
24510 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
24520 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
24530 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
24540 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
24550 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
24560 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
24570 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
24580 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
24590 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
245a0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
245b0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
245c0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
245d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
245e0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
245f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
24600 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
24610 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
24620 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
24630 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
24640 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
24650 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
24660 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
24670 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
24680 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
24690 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
246a0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
246b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
246c0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
246d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
246e0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
246f0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
24700 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
24710 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
24720 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
24730 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
24740 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
24750 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
24760 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
24770 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
24780 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
24790 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
247a0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
247b0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
247c0 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
247d0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
247e0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
247f0 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
24800 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
24810 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
24820 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
24830 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
24840 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
24850 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
24860 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24870 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
24880 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
24890 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
248a0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
248b0 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
248c0 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
248d0 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
248e0 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
248f0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
24900 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
24910 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
24920 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
24930 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
24940 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
24950 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
24960 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
24970 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
24980 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
24990 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
249a0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
249b0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
249c0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
249d0 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
249e0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
249f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
24a00 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
24a10 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
24a20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24a30 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
24a40 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
24a50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24a60 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
24a70 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
24a80 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
24a90 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
24aa0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
24ab0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
24ac0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
24ad0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
24ae0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
24af0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
24b00 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
24b10 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
24b20 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
24b30 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
24b40 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
24b50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
24b60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
24b70 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
24b80 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
24b90 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
24ba0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
24bb0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
24bc0 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
24bd0 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
24be0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
24bf0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
24c00 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
24c10 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
24c20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
24c30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24c40 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
24c50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24c60 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
24c70 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
24c80 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
24c90 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
24ca0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
24cb0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
24cc0 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
24cd0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
24ce0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
24cf0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
24d00 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
24d10 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
24d20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24d30 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
24d40 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
24d50 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
24d60 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
24d70 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
24d80 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
24d90 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
24da0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24db0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
24dc0 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
24dd0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
24de0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
24df0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
24e00 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
24e10 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
24e20 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
24e30 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
24e40 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
24e50 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
24e60 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
24e70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
24e80 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
24e90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
24ea0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
24eb0 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  again..** </li>.
24ec0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
24ed0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
24ee0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
24ef0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
24f00 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
24f10 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
24f20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
24f30 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
24f40 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
24f50 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
24f60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
24f70 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
24f80 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
24f90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
24fa0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
24fb0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
24fc0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
24fd0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
24fe0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24ff0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
25000 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
25010 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
25020 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
25030 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
25040 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
25050 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
25060 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
25070 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
25080 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
25090 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
250a0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
250b0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
250c0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
250d0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
250e0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
250f0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
25100 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
25110 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
25120 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
25130 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
25140 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
25150 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
25160 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
25170 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
25180 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
25190 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
251a0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
251b0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
251c0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
251d0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
251e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
251f0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
25200 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
25210 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
25220 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
25230 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
25240 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
25250 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
25260 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
25270 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
25280 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
25290 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
252a0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
252b0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
252c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
252d0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
252e0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
252f0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
25300 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
25310 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
25320 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
25330 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
25340 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
25350 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25360 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
25370 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
25380 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
25390 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
253a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
253b0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
253c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
253d0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
253e0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
253f0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
25400 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
25410 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
25420 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
25430 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
25440 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
25450 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
25460 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
25470 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
25480 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
25490 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
254a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
254b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
254c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
254d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
254e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
254f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25500 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
25510 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
25520 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
25530 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25540 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25550 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25560 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25570 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25580 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25590 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
255a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
255b0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
255c0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
255d0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
255e0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
255f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
25600 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
25610 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
25620 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
25630 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
25640 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
25650 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
25660 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
25670 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
25680 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
25690 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
256a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
256b0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
256c0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
256d0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
256e0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
256f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
25700 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
25710 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
25720 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
25730 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
25740 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25750 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25760 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
25770 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
25780 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
25790 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
257a0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
257b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
257c0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
257d0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
257e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
257f0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
25800 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
25810 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
25820 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
25830 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
25840 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
25850 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
25860 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
25870 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
25880 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
25890 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
258a0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
258b0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
258c0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
258d0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
258e0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
258f0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
25900 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
25910 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
25920 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
25930 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
25940 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
25950 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
25960 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
25970 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
25980 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
25990 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
259a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
259b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
259c0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
259d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
259e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
259f0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
25a00 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
25a10 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
25a20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25a30 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
25a40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25a50 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
25a60 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
25a70 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
25a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
25a90 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
25aa0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
25ab0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
25ac0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
25ad0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
25ae0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25af0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25b00 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
25b10 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
25b20 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
25b30 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
25b40 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
25b50 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
25b60 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
25b70 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
25b80 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
25b90 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
25ba0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
25bb0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
25bc0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
25bd0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
25be0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
25bf0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
25c00 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
25c10 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
25c20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
25c30 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
25c40 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
25c50 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
25c60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
25c70 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
25c80 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
25c90 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
25ca0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
25cb0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
25cc0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
25cd0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
25ce0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
25cf0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
25d00 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
25d10 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
25d20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
25d30 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
25d40 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
25d50 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
25d60 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
25d70 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
25d80 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
25d90 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
25da0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
25db0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
25dc0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
25dd0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
25de0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
25df0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
25e00 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
25e10 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
25e20 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
25e30 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
25e40 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
25e50 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
25e60 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
25e70 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
25e80 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
25e90 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
25ea0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
25eb0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
25ec0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
25ed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
25ee0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
25ef0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
25f00 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
25f10 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
25f20 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
25f30 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25f40 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
25f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25f60 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
25f70 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
25f80 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
25f90 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
25fa0 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
25fb0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
25fc0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
25fd0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
25fe0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
25ff0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26000 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
26010 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
26020 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
26030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
26040 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
26050 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
26060 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
26070 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
26080 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
26090 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
260a0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
260b0 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
260c0 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
260d0 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
260e0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
260f0 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
26100 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
26110 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
26120 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
26130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26140 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
26150 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
26160 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
26170 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
26180 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
26190 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
261a0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
261b0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
261c0 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
261d0 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
261e0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
261f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
26200 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
26210 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
26220 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
26230 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
26240 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
26250 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
26260 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
26270 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
26280 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
26290 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
262a0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
262b0 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
262c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
262d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
262e0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
262f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26300 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
26310 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
26320 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
26330 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26340 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
26350 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26360 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
26370 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
26380 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
26390 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
263a0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
263b0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
263c0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
263d0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
263e0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
263f0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
26400 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
26410 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
26420 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26430 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
26440 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
26450 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
26460 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
26470 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
26480 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26490 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
264a0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
264b0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
264c0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
264d0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
264e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
264f0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
26500 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
26510 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
26520 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
26530 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
26540 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
26550 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
26560 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
26570 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
26580 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
26590 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
265a0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
265b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
265c0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
265d0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
265e0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
265f0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
26600 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
26610 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
26620 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
26630 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
26640 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
26650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26660 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
26670 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
26680 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
26690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
266a0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
266b0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
266c0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
266d0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
266e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
266f0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
26700 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
26710 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
26720 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
26730 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
26740 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
26750 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
26760 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
26770 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
26780 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
26790 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
267a0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
267b0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
267c0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
267d0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
267e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
267f0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
26800 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
26810 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
26820 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
26830 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
26840 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
26850 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
26860 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
26870 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
26880 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
26890 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
268a0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
268b0 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
268c0 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
268d0 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
268e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
268f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
26900 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
26910 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
26920 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
26930 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
26940 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
26950 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
26960 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
26970 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
26980 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
26990 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
269a0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
269b0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
269c0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
269d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
269e0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
269f0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
26a00 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
26a10 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
26a20 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
26a30 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
26a40 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
26a50 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
26a60 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
26a70 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
26a80 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
26a90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
26aa0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
26ab0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
26ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
26ad0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
26ae0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
26af0 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
26b00 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
26b10 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
26b20 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
26b30 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
26b40 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
26b50 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
26b60 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
26b70 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
26b80 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
26b90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26ba0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
26bb0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
26bc0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
26bd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26be0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
26bf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
26c00 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
26c10 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
26c20 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
26c30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
26c40 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
26c50 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
26c60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
26c70 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
26c80 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
26c90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
26ca0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
26cb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
26cc0 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
26cd0 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
26ce0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
26cf0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
26d00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26d10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26d20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26d30 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
26d40 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
26d50 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
26d60 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
26d70 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
26d80 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
26d90 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
26da0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
26db0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
26dc0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
26dd0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
26de0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
26df0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
26e00 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
26e10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26e20 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
26e30 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
26e40 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
26e50 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
26e60 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
26e70 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
26e80 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
26e90 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
26ea0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
26eb0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
26ec0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
26ed0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
26ee0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
26ef0 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
26f00 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
26f10 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
26f20 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
26f30 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
26f40 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
26f50 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
26f60 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
26f70 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
26f80 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
26f90 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
26fa0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
26fb0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
26fc0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
26fd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26fe0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
26ff0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
27000 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
27010 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
27020 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
27030 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
27040 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
27050 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
27060 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
27070 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
27080 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
27090 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
270a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
270b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
270c0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
270d0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
270e0 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
270f0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
27100 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
27110 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
27120 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
27130 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
27140 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
27150 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
27160 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
27170 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
27180 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
27190 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
271a0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
271b0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
271c0 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
271d0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
271e0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
271f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27200 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
27210 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
27220 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
27230 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
27240 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
27250 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
27260 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
27270 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
27280 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
27290 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
272a0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
272b0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
272c0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
272d0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
272e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
272f0 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
27300 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
27310 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  meter..**.** ^(I
27320 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
27330 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
27340 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
27350 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
27360 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
27370 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
27380 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
27390 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
273a0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
273b0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
273c0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
273d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
273e0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
273f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
27400 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27410 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
27420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27430 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
27440 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
27450 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
27460 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
27470 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
27480 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
27490 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
274a0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
274b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
274c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
274d0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
274e0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
274f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
27500 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
27510 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
27520 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
27530 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
27540 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
27550 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27560 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
27570 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
27580 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
27590 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
275a0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
275b0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
275c0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
275d0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
275e0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
275f0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
27600 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
27610 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
27620 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
27630 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27640 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
27650 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
27660 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
27670 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
27680 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
27690 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
276a0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
276b0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
276c0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
276d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
276e0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
276f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
27700 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
27710 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
27720 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
27730 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
27740 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
27750 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
27760 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
27770 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
27780 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
27790 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
277a0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
277b0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
277c0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
277d0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
277e0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
277f0 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
27800 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27810 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
27820 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
27830 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
27840 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
27850 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
27860 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
27870 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
27880 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
27890 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
278a0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
278b0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
278c0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
278d0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
278e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
278f0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
27900 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
27910 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
27920 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
27930 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
27940 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
27950 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
27960 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
27970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
27980 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
27990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
279a0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
279b0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
279c0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
279d0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
279e0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
279f0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
27a00 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
27a10 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
27a20 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
27a30 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
27a40 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
27a50 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
27a60 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
27a70 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
27a80 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
27a90 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
27aa0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
27ab0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
27ac0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
27ad0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
27ae0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
27af0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
27b00 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
27b10 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
27b20 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
27b30 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
27b40 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
27b50 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
27b60 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27b70 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
27b80 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
27b90 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
27ba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27bb0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
27bc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
27bd0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
27be0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
27bf0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
27c00 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
27c10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27c20 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
27c30 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
27c40 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
27c50 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
27c60 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
27c70 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
27c80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27c90 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
27ca0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
27cb0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
27cc0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
27cd0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
27ce0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
27cf0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
27d00 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
27d10 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
27d20 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
27d30 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
27d40 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
27d50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27d60 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
27d70 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
27d80 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
27d90 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
27da0 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
27db0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
27dc0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
27dd0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
27de0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
27df0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
27e00 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
27e10 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
27e20 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
27e30 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
27e40 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27e50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27e60 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
27e70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27e80 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
27e90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
27ea0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27eb0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
27ec0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27ed0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
27ee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
27ef0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
27f00 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
27f10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
27f20 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
27f30 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
27f40 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
27f50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
27f60 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
27f70 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
27f80 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c  , int, int);.SQL
27f90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
27fa0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
27fb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27fc0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
27fd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
27fe0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
27ff0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
28000 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
28010 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28020 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
28030 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28040 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
28050 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28060 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28070 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
28080 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
28090 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
280a0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
280b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
280c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
280d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
280e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
280f0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
28100 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
28110 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28120 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
28130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28140 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
28150 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
28160 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
28170 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
28180 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
28190 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
281a0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
281b0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
281c0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
281d0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
281e0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
281f0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
28200 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
28210 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
28220 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
28230 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
28240 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
28250 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
28260 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
28270 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
28280 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
28290 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
282a0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
282b0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
282c0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
282d0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
282e0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
282f0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
28300 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
28310 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
28320 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
28330 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
28340 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
28350 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
28360 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
28370 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
28380 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
28390 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
283a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
283b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
283c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
283d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
283e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
283f0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
28400 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28410 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
28420 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28430 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28440 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
28450 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
28460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
28470 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
28480 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
28490 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
284a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
284b0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
284c0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
284d0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
284e0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
284f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
28500 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
28510 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
28520 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
28530 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
28540 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
28550 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
28560 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
28570 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
28580 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
28590 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
285a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
285b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
285c0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
285d0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
285e0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
285f0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
28600 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
28610 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
28620 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
28630 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
28640 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
28650 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
28660 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
28670 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
28680 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
28690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
286a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
286b0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
286c0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
286d0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
286e0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
286f0 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
28700 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
28710 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
28720 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
28730 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
28740 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
28750 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
28760 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
28770 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
28780 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
28790 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
287a0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
287b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
287c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
287d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
287e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
287f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
28800 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
28810 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28820 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
28830 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
28840 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28850 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28860 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
28870 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28880 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28890 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
288a0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
288b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
288c0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
288d0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
288e0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
288f0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
28900 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
28910 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
28920 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
28930 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
28940 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
28950 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
28960 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
28970 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28980 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
28990 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
289a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
289b0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
289c0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
289d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
289e0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
289f0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
28a00 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
28a10 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
28a20 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
28a30 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
28a40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
28a50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
28a60 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
28a70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28a80 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
28a90 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
28aa0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
28ab0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
28ac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28ad0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
28ae0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
28af0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28b00 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
28b10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
28b20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
28b30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28b40 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
28b50 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
28b60 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
28b70 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
28b80 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
28b90 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
28ba0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
28bb0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
28bc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28bd0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
28be0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
28bf0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
28c00 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
28c10 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
28c20 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
28c30 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
28c40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28c50 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
28c60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
28c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28c80 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
28c90 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
28ca0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
28cb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
28cc0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
28cd0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
28ce0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
28cf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28d00 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
28d10 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
28d20 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
28d30 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
28d40 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
28d50 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
28d60 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
28d70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
28d80 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
28d90 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
28da0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
28db0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
28dc0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28de0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
28df0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
28e00 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
28e10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
28e20 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
28e30 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
28e40 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
28e50 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
28e60 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28e70 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
28e80 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
28e90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28ea0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28eb0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28ec0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
28ed0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
28ee0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
28ef0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28f00 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
28f10 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
28f20 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
28f30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28f40 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
28f50 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
28f60 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
28f70 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
28f80 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
28f90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
28fa0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
28fb0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
28fc0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
28fd0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
28fe0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
28ff0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
29000 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
29010 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29020 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
29030 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
29040 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29050 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
29060 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
29070 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
29080 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
29090 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
290a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
290b0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
290c0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
290d0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
290e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
290f0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
29100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
29110 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
29120 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
29130 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
29140 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
29150 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
29160 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
29170 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
29180 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
29190 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
291a0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
291b0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
291c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
291d0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
291e0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
291f0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
29200 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
29210 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
29220 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
29230 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
29240 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
29250 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
29260 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
29270 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
29280 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
29290 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
292a0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
292b0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
292c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
292d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
292e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
292f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29300 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
29310 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
29320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
29330 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
29340 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
29350 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
29360 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
29370 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
29380 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
29390 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
293a0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
293b0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
293c0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
293d0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
293e0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
293f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
29400 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
29410 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
29420 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
29430 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
29440 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
29450 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
29460 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
29470 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
29480 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
29490 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
294a0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
294b0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
294c0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
294d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
294e0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
294f0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
29500 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29510 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
29520 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
29530 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
29540 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
29550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29560 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
29570 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
29580 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
29590 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
295a0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
295b0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
295c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
295d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
295e0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
295f0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
29600 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
29610 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
29620 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
29630 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
29640 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
29650 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
29660 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
29670 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
29680 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
29690 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
296a0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
296b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
296c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
296d0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
296e0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
296f0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
29700 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
29710 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
29720 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
29730 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
29740 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
29750 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
29760 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
29770 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
29780 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
29790 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
297a0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
297b0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
297c0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
297d0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
297e0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
297f0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
29800 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
29810 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
29820 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
29830 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
29840 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
29850 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
29860 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
29870 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
29880 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
29890 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
298a0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
298b0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
298c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
298d0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
298e0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
298f0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
29900 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
29910 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
29920 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
29930 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
29940 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
29950 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
29960 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
29970 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
29980 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
29990 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
299a0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
299b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
299c0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
299d0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
299e0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
299f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
29a00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
29a10 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
29a20 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
29a30 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
29a40 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
29a50 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
29a60 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
29a70 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
29a80 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
29a90 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
29aa0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
29ab0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
29ac0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
29ad0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
29ae0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
29af0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
29b00 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
29b10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
29b20 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
29b30 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
29b40 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
29b50 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
29b60 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
29b70 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
29b80 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
29b90 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
29ba0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
29bb0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29bc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29bd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
29be0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
29bf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
29c00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
29c10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29c20 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
29c30 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
29c40 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
29c50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
29c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
29c70 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
29c80 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
29c90 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
29ca0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29cb0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
29cc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
29cd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
29ce0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29cf0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
29d00 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29d10 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
29d20 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
29d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
29d40 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
29d50 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29d70 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
29d80 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
29d90 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
29da0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
29db0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
29dc0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
29dd0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
29de0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
29df0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
29e00 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
29e10 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
29e20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
29e30 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
29e40 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
29e50 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
29e60 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
29e70 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
29e80 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
29e90 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
29ea0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
29eb0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
29ec0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
29ed0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
29ee0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
29ef0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
29f00 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
29f10 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
29f20 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
29f30 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
29f40 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
29f50 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
29f60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
29f70 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
29f80 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
29f90 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
29fa0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
29fb0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
29fc0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
29fd0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
29fe0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
29ff0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2a000 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2a010 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2a020 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2a030 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2a040 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2a050 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2a060 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2a070 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2a080 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2a090 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2a0a0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2a0b0 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2a0c0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2a0d0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2a0e0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2a0f0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2a100 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2a110 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2a120 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2a130 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2a140 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2a150 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2a160 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2a170 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2a180 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2a190 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2a1a0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2a1b0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2a1c0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2a1d0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2a1e0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2a1f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a200 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a210 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2a220 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a230 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2a240 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a250 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2a260 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2a270 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2a280 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2a290 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2a2a0 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
2a2b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a2c0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2a2d0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2a2e0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2a2f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a300 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2a310 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2a320 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2a330 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2a340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a350 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2a360 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2a370 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2a380 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2a390 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2a3a0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2a3b0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2a3c0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2a3d0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2a3e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2a3f0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2a400 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2a410 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2a420 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2a430 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2a440 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2a450 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a460 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2a470 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a480 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2a490 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2a4a0 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2a4b0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2a4c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2a4d0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2a4e0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2a4f0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2a500 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2a510 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2a520 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2a530 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2a540 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2a550 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2a560 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2a570 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2a580 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2a590 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2a5a0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2a5b0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2a5c0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2a5d0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2a5e0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2a5f0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2a600 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2a610 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2a620 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2a630 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2a640 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2a650 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2a660 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2a670 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2a680 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2a690 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2a6a0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2a6b0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2a6c0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2a6d0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2a6e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2a6f0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2a700 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2a710 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2a720 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2a730 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2a740 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2a750 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2a760 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2a770 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2a780 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2a790 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2a7a0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2a7b0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2a7c0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2a7d0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2a7e0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2a7f0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2a800 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2a810 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2a820 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2a830 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2a840 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2a850 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2a860 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2a870 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2a880 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2a890 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a8a0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2a8b0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2a8c0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2a8d0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2a8e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2a8f0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2a900 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2a910 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2a920 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2a930 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2a940 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2a950 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2a960 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2a970 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2a980 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2a990 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2a9a0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2a9b0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2a9c0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2a9d0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2a9e0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2a9f0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2aa00 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2aa10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2aa20 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2aa30 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2aa40 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2aa50 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2aa60 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2aa70 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2aa80 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2aa90 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2aaa0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2aab0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2aac0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2aad0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2aae0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2aaf0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2ab00 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2ab10 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2ab20 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2ab30 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2ab40 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2ab50 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2ab60 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2ab70 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2ab80 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2ab90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2aba0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2abb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2abc0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2abd0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2abe0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2abf0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2ac00 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2ac10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2ac20 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2ac30 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2ac40 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2ac50 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2ac60 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2ac70 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2ac80 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2ac90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aca0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2acb0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2acc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2acd0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2ace0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2acf0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2ad00 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2ad10 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2ad20 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2ad30 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2ad40 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2ad50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ad60 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2ad70 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2ad80 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2ad90 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2ada0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2adb0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2adc0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2add0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2ade0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2adf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2ae00 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2ae10 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2ae20 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2ae30 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2ae40 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2ae50 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2ae60 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2ae70 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2ae80 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2ae90 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2aea0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2aeb0 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2aec0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2aed0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2aee0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2aef0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2af00 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2af10 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2af20 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2af30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2af40 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2af50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2af60 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2af70 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2af80 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2af90 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2afa0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2afb0 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2afc0 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2afd0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2afe0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2aff0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2b000 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2b010 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2b020 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2b030 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2b040 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2b050 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2b060 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2b070 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2b080 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2b090 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2b0a0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2b0b0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2b0c0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2b0d0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2b0e0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2b0f0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2b100 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2b110 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2b120 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2b130 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2b140 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2b150 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2b160 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2b170 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2b180 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b190 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2b1a0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2b1b0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2b1c0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2b1d0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2b1e0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2b1f0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2b200 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2b210 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2b220 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2b230 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2b240 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2b250 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2b260 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2b270 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2b280 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2b290 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2b2a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b2b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b2c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2b2d0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2b2e0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2b2f0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2b300 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b310 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2b320 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2b330 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2b340 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2b350 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2b360 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2b370 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2b380 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2b390 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2b3a0 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nded..*/.SQLITE_
2b3b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b3c0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2b3d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b3e0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2b3f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2b400 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2b410 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2b420 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2b430 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2b440 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2b450 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2b460 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2b470 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2b480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b490 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2b4a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2b4b0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2b4c0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2b4d0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2b4e0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2b4f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2b500 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b510 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2b520 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2b530 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b540 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2b550 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2b560 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2b570 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2b580 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2b590 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2b5a0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2b5b0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2b5c0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2b5d0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2b5e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2b5f0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2b600 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2b610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2b620 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2b630 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2b640 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2b650 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b660 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2b670 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2b680 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2b690 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2b6a0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2b6b0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2b6c0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2b6d0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2b6e0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2b6f0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2b700 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2b710 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2b720 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b730 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b740 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2b750 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b760 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
2b770 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2b780 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2b790 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
2b7a0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
2b7b0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2b7c0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
2b7d0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
2b7e0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
2b7f0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
2b800 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
2b810 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
2b820 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2b830 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
2b840 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
2b850 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
2b860 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
2b870 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
2b880 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
2b890 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2b8a0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2b8b0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2b8c0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2b8d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2b8e0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2b8f0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2b900 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2b910 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2b920 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2b930 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2b940 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2b950 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2b960 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2b970 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2b980 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2b990 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2b9a0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2b9b0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2b9c0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2b9d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b9e0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2b9f0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2ba00 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2ba10 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2ba20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2ba30 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2ba40 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2ba50 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2ba60 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2ba70 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2ba80 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2ba90 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2baa0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2bab0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
2bac0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
2bad0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2bae0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2baf0 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
2bb00 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
2bb10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2bb20 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
2bb30 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2bb40 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
2bb50 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
2bb60 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
2bb70 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
2bb80 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
2bb90 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
2bba0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2bbb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2bbc0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
2bbd0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
2bbe0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2bbf0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
2bc00 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
2bc10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bc20 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2bc30 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
2bc40 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
2bc50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2bc60 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2bc70 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
2bc80 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
2bc90 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
2bca0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
2bcb0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2bcc0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
2bcd0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
2bce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2bcf0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2bd00 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
2bd10 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
2bd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2bd30 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
2bd40 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2bd50 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
2bd60 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
2bd70 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
2bd80 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
2bd90 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2bda0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
2bdb0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2bdc0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2bdd0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
2bde0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
2bdf0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2be00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2be10 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2be20 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
2be30 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
2be40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2be50 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
2be60 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
2be70 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
2be80 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
2be90 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2bea0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
2beb0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
2bec0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2bed0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2bee0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
2bef0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2bf00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
2bf10 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
2bf20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
2bf30 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2bf40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2bf50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bf60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2bf70 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2bf80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
2bf90 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2bfa0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
2bfb0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
2bfc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2bfd0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
2bfe0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2bff0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2c000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c010 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2c020 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2c030 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2c040 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2c050 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
2c060 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
2c070 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
2c080 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
2c090 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
2c0a0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2c0b0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
2c0c0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2c0d0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
2c0e0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
2c0f0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
2c100 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
2c110 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2c120 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2c130 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
2c140 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
2c150 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
2c160 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
2c170 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
2c180 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
2c190 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
2c1a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
2c1b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2c1c0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
2c1d0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
2c1e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2c1f0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
2c200 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2c210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2c220 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
2c230 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
2c240 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
2c250 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2c260 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
2c270 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2c280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c290 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
2c2a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c2b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c2c0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2c2d0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2c2e0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2c2f0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2c300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c310 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2c320 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2c330 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2c340 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2c350 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2c360 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c370 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2c380 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c390 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
2c3a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2c3b0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2c3c0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2c3d0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
2c3e0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2c3f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c400 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2c410 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2c420 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2c430 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2c440 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
2c450 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2c460 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c470 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
2c480 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
2c490 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2c4a0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
2c4b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2c4c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2c4d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2c4e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2c4f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2c500 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
2c510 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2c520 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
2c530 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2c540 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
2c550 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2c560 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2c570 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2c580 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2c590 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2c5a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c5b0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
2c5c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2c5d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2c5e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2c5f0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
2c600 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2c610 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c620 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2c630 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c640 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2c650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c660 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
2c670 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
2c680 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2c690 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2c6a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2c6b0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
2c6c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2c6d0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
2c6e0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2c6f0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
2c700 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
2c710 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
2c720 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
2c730 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2c740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c750 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c760 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c770 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
2c780 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
2c790 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
2c7a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2c7b0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
2c7c0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
2c7d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c7e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
2c7f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c800 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
2c810 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
2c820 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
2c830 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
2c840 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
2c850 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
2c860 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
2c870 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2c880 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
2c890 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2c8a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2c8b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2c8c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2c8d0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2c8e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c8f0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
2c900 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c910 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
2c920 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
2c930 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
2c940 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
2c950 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
2c960 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
2c970 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
2c980 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c990 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
2c9a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2c9b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2c9c0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
2c9d0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
2c9e0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
2c9f0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2ca00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ca10 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
2ca20 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2ca30 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2ca40 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
2ca50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2ca60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2ca70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2ca80 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
2ca90 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2caa0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
2cab0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
2cac0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2cad0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2cae0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2caf0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2cb00 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2cb10 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2cb20 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2cb30 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2cb40 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2cb50 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2cb60 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
2cb70 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
2cb80 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
2cb90 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
2cba0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
2cbb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2cbc0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2cbd0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
2cbe0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
2cbf0 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
2cc00 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
2cc10 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
2cc20 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2cc30 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2cc40 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
2cc50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2cc60 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2cc70 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2cc80 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
2cc90 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2cca0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
2ccb0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
2ccc0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2ccd0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2cce0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
2ccf0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
2cd00 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2cd10 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2cd20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2cd30 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
2cd40 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
2cd50 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2cd60 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2cd70 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2cd80 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
2cd90 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
2cda0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2cdb0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2cdc0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
2cdd0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2cde0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
2cdf0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2ce00 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
2ce10 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
2ce20 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2ce30 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2ce40 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2ce50 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
2ce60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2ce70 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
2ce80 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2ce90 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
2cea0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2ceb0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2cec0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
2ced0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2cee0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
2cef0 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
2cf00 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2cf10 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2cf20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
2cf30 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
2cf40 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2cf50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2cf60 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2cf70 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
2cf80 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2cf90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
2cfa0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2cfb0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2cfc0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
2cfd0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2cfe0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2cff0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
2d000 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
2d010 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
2d020 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2d030 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
2d040 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
2d050 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
2d060 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
2d070 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
2d080 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
2d090 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
2d0a0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
2d0b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
2d0c0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
2d0d0 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
2d0e0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
2d0f0 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
2d100 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
2d110 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
2d120 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
2d130 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
2d140 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
2d150 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
2d160 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
2d170 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
2d180 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
2d190 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
2d1a0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
2d1b0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2d1c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2d1d0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
2d1e0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
2d1f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2d200 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
2d210 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2d220 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
2d230 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
2d240 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
2d250 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
2d260 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
2d270 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2d280 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2d290 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
2d2a0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
2d2b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2d2c0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2d2d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d2e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
2d2f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
2d300 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
2d310 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
2d320 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
2d330 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2d340 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2d350 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
2d360 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d370 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
2d380 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2d390 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2d3a0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2d3b0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2d3c0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2d3d0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
2d3e0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2d3f0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2d400 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
2d410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d420 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
2d430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d440 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
2d450 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2d460 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2d470 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
2d480 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
2d490 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
2d4a0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
2d4b0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
2d4c0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
2d4d0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
2d4e0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
2d4f0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
2d500 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
2d510 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
2d520 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
2d530 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
2d540 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
2d550 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
2d560 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2d570 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2d580 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2d590 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2d5a0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2d5b0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2d5c0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2d5d0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2d5e0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2d5f0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2d600 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2d610 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2d620 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2d630 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2d640 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2d650 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2d660 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2d670 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2d680 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2d690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2d6a0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2d6b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d6c0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2d6d0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2d6e0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
2d6f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2d700 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2d710 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2d720 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2d730 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2d740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d750 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
2d760 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
2d770 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
2d780 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
2d790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
2d7a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2d7b0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
2d7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d7d0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
2d7e0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
2d7f0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
2d800 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
2d810 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2d820 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2d830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2d840 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
2d850 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
2d860 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
2d870 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
2d880 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
2d890 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
2d8a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2d8b0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
2d8c0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2d8d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
2d8e0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
2d8f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2d900 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
2d910 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
2d920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d930 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
2d940 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2d950 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
2d960 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
2d970 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
2d980 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
2d990 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
2d9a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2d9b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2d9c0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2d9d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
2d9e0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
2d9f0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
2da00 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
2da10 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
2da20 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
2da30 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
2da40 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
2da50 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2da60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2da70 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
2da80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2da90 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
2daa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
2dab0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
2dac0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2dad0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
2dae0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
2daf0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
2db00 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2db10 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
2db20 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
2db30 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
2db40 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
2db50 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
2db60 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
2db70 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
2db80 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2db90 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
2dba0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2dbb0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
2dbc0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
2dbd0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
2dbe0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2dbf0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2dc00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2dc10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2dc20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2dc30 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2dc40 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2dc50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2dc60 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2dc70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2dc80 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2dc90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2dca0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2dcb0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2dcc0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2dcd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2dce0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2dcf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2dd00 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2dd10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2dd20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
2dd30 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2dd40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2dd50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2dd60 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2dd70 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
2dd80 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2dd90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2dda0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ddb0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2ddc0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2ddd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dde0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2ddf0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2de00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2de10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2de20 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2de30 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2de40 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
2de50 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
2de60 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
2de70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2de80 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
2de90 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
2dea0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2deb0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2dec0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2ded0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
2dee0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
2def0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
2df00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2df10 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2df20 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2df30 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
2df40 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
2df50 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
2df60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2df70 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
2df80 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
2df90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
2dfa0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
2dfb0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
2dfc0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2dfd0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
2dfe0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
2dff0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
2e000 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
2e010 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
2e020 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
2e030 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
2e040 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2e050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2e060 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
2e070 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2e080 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2e090 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
2e0a0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
2e0b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
2e0c0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
2e0d0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
2e0e0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
2e0f0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
2e100 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2e110 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
2e120 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
2e130 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2e140 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
2e150 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2e160 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2e170 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
2e180 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
2e190 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
2e1a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
2e1b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2e1c0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
2e1d0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
2e1e0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
2e1f0 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
2e200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e210 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
2e220 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
2e230 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
2e240 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
2e250 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2e260 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
2e270 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
2e280 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2e290 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2e2a0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
2e2b0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
2e2c0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2e2d0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2e2e0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
2e2f0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
2e300 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
2e310 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
2e320 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
2e330 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
2e340 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e350 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2e360 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2e370 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2e380 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2e390 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2e3a0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2e3b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2e3c0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2e3d0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2e3e0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2e3f0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2e400 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2e410 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2e420 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2e430 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2e440 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2e450 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2e460 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2e470 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2e480 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2e490 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2e4a0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2e4b0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2e4c0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2e4d0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2e4e0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2e4f0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2e500 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2e510 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2e520 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2e530 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e540 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2e550 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2e560 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2e570 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2e580 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2e590 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2e5a0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2e5b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e5c0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2e5d0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2e5e0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2e5f0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2e600 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2e610 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2e620 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2e630 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2e640 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2e650 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2e660 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2e670 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2e680 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2e690 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2e6a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e6b0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2e6c0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2e6d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2e6e0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2e6f0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2e700 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2e710 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e720 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2e730 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2e740 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2e750 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2e760 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2e770 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2e780 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2e790 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2e7a0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2e7b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2e7c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2e7d0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2e7e0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2e7f0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2e800 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2e810 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2e820 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2e830 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e840 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2e850 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2e860 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e870 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2e880 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2e890 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2e8a0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2e8b0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2e8c0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2e8d0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2e8e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2e8f0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2e900 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2e910 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2e920 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2e930 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2e940 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2e950 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
2e960 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
2e970 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
2e980 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
2e990 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
2e9a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2e9b0 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
2e9c0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2e9d0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
2e9e0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
2e9f0 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
2ea00 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2ea10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
2ea20 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2ea30 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2ea40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2ea50 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2ea60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2ea70 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2ea80 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2ea90 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
2eaa0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
2eab0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2eac0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2ead0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
2eae0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2eaf0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2eb00 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
2eb10 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
2eb20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
2eb30 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
2eb40 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2eb50 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
2eb60 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2eb70 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
2eb80 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
2eb90 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
2eba0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2ebb0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2ebc0 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
2ebd0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
2ebe0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
2ebf0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2ec00 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
2ec10 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
2ec20 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2ec30 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
2ec40 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
2ec50 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
2ec60 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
2ec70 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
2ec80 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
2ec90 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
2eca0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
2ecb0 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
2ecc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2ecd0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
2ece0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
2ecf0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ed00 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2ed10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2ed20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2ed30 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
2ed40 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
2ed50 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2ed60 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2ed70 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2ed80 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2ed90 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
2eda0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
2edb0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
2edc0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2edd0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2ede0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
2edf0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
2ee00 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
2ee10 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2ee20 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
2ee30 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
2ee40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2ee50 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
2ee60 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2ee70 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2ee80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2ee90 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2eea0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2eeb0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2eec0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2eed0 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e  .  Every SQL fun
2eee0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2eef0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c  tion must be abl
2ef00 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
2ef10 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2ef20 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2ef30 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2ef40 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2ef50 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2ef60 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2ef70 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2ef80 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  r.  ^An applicat
2ef90 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b  ion may.** invok
2efa0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2efb0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2efc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2efd0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2efe0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2eff0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2f000 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2f010 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2f020 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57   eTextRep..** ^W
2f030 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
2f040 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2f050 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2f060 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
2f070 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
2f080 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
2f090 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
2f0a0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2f0b0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
2f0c0 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
2f0d0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
2f0e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
2f0f0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
2f100 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
2f110 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
2f120 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
2f130 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
2f140 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
2f150 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
2f160 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2f170 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2f180 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2f190 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2f1a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2f1b0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2f1c0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2f1d0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2f1e0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
2f1f0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
2f200 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
2f210 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2f220 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2f230 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2f240 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2f250 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2f260 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2f270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2f280 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
2f290 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2f2a0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2f2b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f2c0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2f2d0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
2f2e0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
2f2f0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
2f300 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
2f310 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
2f320 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
2f330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2f340 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2f350 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2f360 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2f370 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
2f380 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2f390 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
2f3a0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2f3b0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2f3c0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2f3d0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
2f3e0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
2f3f0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
2f400 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
2f410 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
2f420 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f430 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f440 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
2f450 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
2f460 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
2f470 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f480 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
2f490 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
2f4a0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
2f4b0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
2f4c0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
2f4d0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
2f4e0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
2f4f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f500 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
2f510 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
2f520 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
2f530 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
2f540 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2f550 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2f560 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
2f570 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
2f580 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
2f590 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
2f5a0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
2f5b0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
2f5c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2f5d0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
2f5e0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
2f5f0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
2f600 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
2f610 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
2f620 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2f630 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2f640 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
2f650 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2f660 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2f670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2f680 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2f690 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2f6a0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2f6b0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2f6c0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2f6d0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2f6e0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2f6f0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2f700 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
2f710 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
2f720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
2f730 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
2f740 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2f750 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2f760 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2f770 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
2f780 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2f790 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
2f7a0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
2f7b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
2f7c0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
2f7d0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2f7e0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
2f7f0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
2f800 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
2f810 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
2f820 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2f830 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
2f840 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
2f850 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
2f860 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2f870 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2f880 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2f890 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
2f8a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2f8b0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2f8c0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
2f8d0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
2f8e0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
2f8f0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
2f900 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2f910 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2f920 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
2f930 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
2f940 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
2f950 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
2f960 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
2f970 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
2f980 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f990 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
2f9a0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
2f9b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2f9c0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2f9d0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
2f9e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
2f9f0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
2fa00 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
2fa10 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
2fa20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2fa30 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
2fa40 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2fa50 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2fa60 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
2fa70 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2fa80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2fa90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2faa0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
2fab0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2fac0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2fad0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2fae0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2faf0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2fb00 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2fb10 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2fb20 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2fb30 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2fb40 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2fb50 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2fb60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2fb70 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2fb80 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fb90 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
2fba0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
2fbb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2fbc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2fbd0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2fbe0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2fbf0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2fc00 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2fc10 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2fc20 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2fc30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2fc40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fc50 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2fc60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2fc70 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2fc80 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2fc90 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2fca0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
2fcb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2fcc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fcd0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
2fce0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2fcf0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2fd00 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2fd10 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2fd20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2fd30 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2fd40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2fd50 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2fd60 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2fd70 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2fd80 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2fd90 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2fda0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2fdb0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
2fdc0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
2fdd0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2fde0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
2fdf0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
2fe00 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
2fe10 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
2fe20 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
2fe30 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
2fe40 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
2fe50 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
2fe60 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
2fe70 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
2fe80 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2fe90 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
2fea0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2feb0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
2fec0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
2fed0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
2fee0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
2fef0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
2ff00 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
2ff10 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
2ff20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
2ff30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ff40 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
2ff50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2ff60 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
2ff70 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2ff80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
2ff90 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
2ffa0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
2ffb0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
2ffc0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
2ffd0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2ffe0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
2fff0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
30000 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
30010 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
30020 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
30030 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
30040 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
30050 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
30060 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
30070 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
30080 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
30090 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
300a0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
300b0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
300c0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
300d0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
300e0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
300f0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
30100 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
30110 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
30120 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
30130 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  D.SQLITE_API SQL
30140 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
30150 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
30160 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
30170 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
30180 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
30190 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
301a0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
301b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
301c0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
301d0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
301e0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
301f0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
30200 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
30210 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
30220 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
30230 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
30240 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
30250 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
30260 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
30270 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
30280 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
30290 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
302a0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
302b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
302c0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
302d0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
302e0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
302f0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
30300 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
30310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
30320 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
30330 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
30340 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
30350 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
30360 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
30370 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
30380 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
30390 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
303a0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
303b0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
303c0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
303d0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
303e0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
303f0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
30400 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
30410 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
30420 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
30430 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
30440 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
30450 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
30460 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
30470 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
30480 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
30490 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
304a0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
304b0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
304c0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
304d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
304e0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
304f0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
30500 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
30510 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30520 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
30530 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
30540 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30550 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
30560 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
30570 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
30580 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
30590 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
305a0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
305b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
305c0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
305d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
305e0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
305f0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
30600 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30610 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
30620 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
30630 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
30640 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30650 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
30660 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
30670 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
30680 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
30690 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
306a0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
306b0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
306c0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
306d0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
306e0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
306f0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
30700 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
30710 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30720 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
30730 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
30740 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
30750 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
30760 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
30770 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30780 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30790 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
307a0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
307b0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
307c0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
307d0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
307e0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
307f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30800 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
30810 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30820 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
30830 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
30840 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
30850 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
30860 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
30870 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
30880 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
30890 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
308a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
308b0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
308c0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
308d0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
308e0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
308f0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
30900 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
30910 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
30920 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
30930 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
30940 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
30950 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
30960 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
30970 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
30980 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
30990 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
309a0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
309b0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
309c0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
309d0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
309e0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
309f0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
30a00 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
30a10 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
30a20 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
30a30 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
30a40 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
30a50 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
30a60 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
30a70 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
30a80 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
30a90 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
30aa0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
30ab0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
30ac0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
30ad0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
30ae0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
30af0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
30b00 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
30b10 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
30b20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30b30 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
30b40 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
30b50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
30b60 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
30b70 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
30b80 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
30b90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
30ba0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
30bb0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
30bc0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
30bd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
30be0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
30bf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
30c00 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51  arameters..*/.SQ
30c10 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
30c20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
30c30 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
30c40 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
30c50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30c60 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
30c70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
30c80 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
30c90 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
30ca0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
30cb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
30cc0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
30cd0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
30ce0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
30cf0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30d00 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
30d10 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
30d20 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
30d30 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
30d40 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
30d50 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
30d60 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
30d70 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
30d80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
30d90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
30da0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
30db0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
30dc0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
30dd0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
30de0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
30df0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
30e00 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
30e10 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
30e20 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
30e30 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
30e40 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
30e50 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
30e60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30e70 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
30e80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
30e90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
30ea0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
30eb0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
30ec0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
30ed0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
30ee0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
30ef0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
30f00 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
30f10 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
30f20 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
30f30 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
30f40 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
30f50 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
30f60 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
30f70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
30f80 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
30f90 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
30fa0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
30fb0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
30fc0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
30fd0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
30fe0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
30ff0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
31000 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
31010 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
31020 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
31030 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
31040 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
31050 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
31060 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
31070 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31080 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
31090 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
310a0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
310b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
310c0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
310d0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
310e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
310f0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
31100 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
31110 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
31120 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
31130 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
31140 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
31150 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
31160 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
31170 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
31180 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
31190 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
311a0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
311b0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
311c0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
311d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
311e0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
311f0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
31200 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
31210 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
31220 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
31230 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31240 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
31250 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
31260 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
31270 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
31280 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
31290 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
312a0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
312b0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
312c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20  LL pointer if N 
312d0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
312e0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
312f0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
31300 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
31310 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
31320 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
31330 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
31340 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31350 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
31360 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
31370 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
31380 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
31390 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
313a0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
313b0 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
313c0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
313d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
313e0 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
313f0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
31400 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
31410 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
31420 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
31430 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
31440 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  on.)^.**.** ^SQL
31450 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
31460 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
31470 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
31480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
31490 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
314a0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
314b0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
314c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
314d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
314e0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
314f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
31500 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
31510 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
31520 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
31530 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
31540 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
31550 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
31560 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
31570 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
31580 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
31590 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
315a0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
315b0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
315c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
315d0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
315e0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
315f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
31600 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
31610 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31620 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
31630 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
31640 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
31650 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
31660 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
31670 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
31680 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
31690 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
316a0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
316b0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
316c0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
316d0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
316e0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
316f0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
31700 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31710 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
31720 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31730 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
31740 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
31750 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
31760 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
31770 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
31780 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
31790 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
317a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
317b0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
317c0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
317d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
317e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
317f0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
31800 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
31810 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
31820 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
31830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31840 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
31850 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
31860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31870 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
31880 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
31890 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
318a0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
318b0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
318c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
318d0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
318e0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
318f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31900 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
31910 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31920 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
31930 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
31940 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
31950 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
31960 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
31970 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  nction..*/.SQLIT
31980 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73  E_API sqlite3 *s
31990 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
319a0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
319b0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
319c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
319d0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
319e0 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
319f0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
31a00 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
31a10 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
31a20 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
31a30 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
31a40 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
31a50 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
31a60 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
31a70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
31a80 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
31a90 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
31aa0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
31ab0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
31ac0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
31ad0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
31ae0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
31af0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
31b00 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
31b10 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
31b20 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
31b30 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
31b40 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
31b50 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
31b60 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
31b70 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
31b80 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
31b90 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
31ba0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
31bb0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
31bc0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
31bd0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
31be0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
31bf0 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
31c00 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
31c10 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
31c20 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
31c30 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
31c40 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
31c50 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
31c60 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
31c70 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
31c80 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
31c90 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
31ca0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
31cb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31cc0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
31cd0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
31ce0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
31cf0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
31d00 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
31d10 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
31d20 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
31d30 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
31d40 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
31d50 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
31d60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31d70 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64  on. ^If no metad
31d80 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
31d90 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
31da0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
31db0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
31dc0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
31dd0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
31de0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
31df0 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
31e00 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
31e10 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
31e20 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
31e30 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
31e40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
31e50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31e60 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
31e70 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
31e80 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
31e90 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
31ea0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
31eb0 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
31ec0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
31ed0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
31ee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31ef0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
31f00 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
31f10 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31f20 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
31f30 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
31f40 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
31f50 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
31f60 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74  royed..** ^If it
31f70 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
31f80 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
31f90 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
31fa0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
31fb0 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
31fc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
31fd0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
31fe0 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
31ff0 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
32000 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
32010 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
32020 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
32030 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
32040 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
32050 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
32060 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
32070 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
32080 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
32090 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
320a0 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
320b0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
320c0 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
320d0 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75  e.  ^The only gu
320e0 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
320f0 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
32100 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
32110 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
32120 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
32130 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
32140 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
32150 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
32160 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
32170 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
32180 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
32190 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
321a0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
321b0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
321c0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
321d0 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a  rameters].)^.**.
321e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
321f0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
32200 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
32210 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
32220 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
32230 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
32240 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
32250 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
32260 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
32270 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
32280 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
32290 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
322a0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
322b0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
322c0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
322d0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
322e0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
322f0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
32300 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
32310 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
32320 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
32330 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
32340 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
32350 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
32360 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
32370 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
32380 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
32390 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
323a0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
323b0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
323c0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
323d0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
323e0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
323f0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
32400 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
32410 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
32420 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
32430 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
32440 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
32450 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
32460 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
32470 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
32480 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
32490 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
324a0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
324b0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
324c0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
324d0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
324e0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
324f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
32500 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
32510 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
32520 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
32530 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
32540 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
32550 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
32560 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
32570 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
32580 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
32590 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
325a0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
325b0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
325c0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
325d0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
325e0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
325f0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
32600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
32610 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
32620 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
32630 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
32640 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
32650 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
32660 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
32670 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
32680 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
32690 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
326a0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
326b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
326c0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
326d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
326e0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
326f0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
32700 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
32710 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
32720 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
32730 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
32740 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
32750 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
32760 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
32770 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
32780 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
32790 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
327a0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
327b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
327c0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
327d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
327e0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
327f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32800 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
32810 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
32820 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
32830 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32840 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32850 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
32860 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
32870 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
32880 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32890 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
328a0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
328b0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
328c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
328d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
328e0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
328f0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
32900 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
32910 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
32920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32930 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
32940 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
32950 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
32960 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
32970 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
32980 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
32990 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
329a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
329b0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
329c0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
329d0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
329e0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
329f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32a00 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
32a10 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
32a20 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
32a30 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
32a40 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
32a50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32a60 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
32a70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32a80 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
32a90 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
32aa0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
32ab0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
32ac0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
32ad0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
32ae0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
32af0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
32b00 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
32b10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32b20 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
32b30 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
32b40 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
32b50 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
32b60 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
32b70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
32b80 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
32b90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
32ba0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
32bb0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
32bc0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
32bd0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
32be0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32bf0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
32c00 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
32c10 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
32c20 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
32c30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
32c40 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
32c50 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
32c60 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
32c70 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
32c80 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
32c90 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
32ca0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
32cb0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
32cc0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
32cd0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
32ce0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
32cf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32d00 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
32d10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32d20 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
32d30 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
32d40 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
32d50 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
32d60 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
32d70 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
32d80 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
32d90 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
32da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32db0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
32dc0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32dd0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
32de0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
32df0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
32e00 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
32e10 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
32e20 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
32e30 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
32e40 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
32e50 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
32e60 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
32e70 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
32e80 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
32e90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32ea0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
32eb0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
32ec0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
32ed0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
32ee0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
32ef0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
32f00 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
32f10 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
32f20 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
32f30 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
32f40 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
32f50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32f60 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
32f70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32f80 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
32f90 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
32fa0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
32fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32fc0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
32fd0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
32fe0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
32ff0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33000 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33010 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
33020 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
33030 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
33040 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33050 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
33060 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
33070 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33080 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33090 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
330a0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
330b0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
330c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
330d0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
330e0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
330f0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33100 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33110 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33120 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
33130 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33140 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33150 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33160 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
33170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33180 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
33190 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
331a0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
331b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
331c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
331d0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
331e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
331f0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
33200 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
33210 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33220 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
33230 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33240 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
33250 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
33260 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33270 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33280 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
33290 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
332a0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
332b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
332c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
332d0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
332e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
332f0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
33300 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
33310 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
33320 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33330 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33340 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
33350 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
33360 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
33370 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
33380 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
33390 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
333a0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
333b0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
333c0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
333d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
333e0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
333f0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
33400 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
33410 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33420 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
33430 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
33440 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
33450 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33460 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
33470 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
33480 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
33490 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
334a0 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
334b0 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
334c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
334d0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
334e0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
334f0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
33500 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
33510 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33520 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33530 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
33540 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
33550 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
33560 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
33570 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
33580 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
33590 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
335a0 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
335b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
335c0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
335d0 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
335e0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
335f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
33600 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
33610 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
33620 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
33630 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
33640 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
33650 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
33660 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
33670 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
33680 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
33690 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
336a0 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
336b0 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
336c0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
336d0 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
336e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
336f0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
33700 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
33710 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
33720 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
33730 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
33740 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
33750 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
33760 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
33770 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
33780 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
33790 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
337a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
337b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
337c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
337d0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
337e0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
337f0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
33800 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
33810 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
33820 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
33830 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
33840 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
33850 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
33860 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
33870 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
33880 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33890 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
338a0 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
338b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
338c0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
338d0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
338e0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
338f0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
33900 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
33910 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
33920 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
33930 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
33940 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
33950 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
33960 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
33970 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
33980 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
33990 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
339a0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
339b0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
339c0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
339d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
339e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
339f0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
33a00 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
33a10 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
33a20 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
33a30 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
33a40 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
33a50 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
33a60 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
33a70 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
33a80 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
33a90 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
33aa0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
33ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33ac0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
33ad0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33ae0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
33af0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33b00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33b10 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
33b20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33b30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33b40 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
33b50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33b60 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
33b70 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
33b80 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
33b90 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
33ba0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
33bb0 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
33bc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33bd0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
33be0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
33bf0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
33c00 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
33c10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33c20 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
33c30 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
33c40 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
33c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33c60 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
33c70 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
33c80 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
33c90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33ca0 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
33cb0 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
33cc0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
33cd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33ce0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
33cf0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
33d00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
33d10 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
33d20 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
33d30 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
33d40 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
33d50 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
33d60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33d70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33d80 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
33d90 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
33da0 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
33db0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
33dc0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
33dd0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33de0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33df0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
33e00 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
33e10 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
33e20 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
33e30 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
33e40 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
33e50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33e60 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
33e70 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33e80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
33e90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33ea0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
33eb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
33ec0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33ed0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
33ee0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33ef0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  t void*, int);.S
33f00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33f10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33f20 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
33f30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
33f40 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
33f50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33f60 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
33f70 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
33f80 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
33f90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33fa0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
33fb0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
33fc0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
33fd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
33fe0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33ff0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
34000 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34010 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
34020 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34030 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
34040 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
34060 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
34070 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
34080 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34090 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
340a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
340b0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
340c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
340d0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
340e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
340f0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
34100 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34110 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
34120 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
34130 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34140 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34150 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
34160 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34170 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
34180 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
34190 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
341a0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
341b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
341c0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
341d0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
341e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
341f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34200 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
34210 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
34220 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34230 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34240 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
34250 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
34260 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
34270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
34280 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
34290 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
342a0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
342b0 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
342c0 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
342d0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
342e0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
342f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34300 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
34310 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
34320 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34330 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
34340 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
34350 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
34360 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34370 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
34380 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34390 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
343a0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
343b0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
343c0 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
343d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
343e0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
343f0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
34400 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
34410 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
34420 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
34430 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
34440 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
34450 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
34460 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
34470 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
34480 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
34490 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
344a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
344b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
344c0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
344d0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
344e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
344f0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
34500 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
34510 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34520 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
34530 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
34540 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
34550 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
34560 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
34570 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
34580 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
34590 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
345a0 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
345b0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
345c0 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
345d0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
345e0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
345f0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
34600 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
34610 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
34620 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
34630 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
34640 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
34650 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
34660 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
34670 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
34680 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
34690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
346a0 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
346b0 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
346c0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
346d0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
346e0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
346f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34700 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
34710 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
34720 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
34730 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
34740 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
34750 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
34760 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34770 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
34780 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34790 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
347a0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
347b0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
347c0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
347d0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
347e0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
347f0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
34800 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
34810 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
34820 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
34830 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
34840 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
34850 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
34860 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
34870 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34880 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
34890 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
348a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
348b0 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
348c0 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
348d0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
348e0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
348f0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
34900 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
34910 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
34920 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
34930 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
34940 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
34950 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
34960 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
34970 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
34980 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
34990 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
349a0 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
349b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
349c0 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
349d0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
349e0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
349f0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
34a00 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
34a10 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
34a20 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
34a30 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
34a40 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
34a50 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
34a60 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34a70 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
34a80 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
34a90 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
34aa0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
34ab0 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
34ac0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34ad0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
34ae0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
34af0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
34b00 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
34b10 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
34b20 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
34b30 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
34b40 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
34b50 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
34b60 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
34b70 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
34b80 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
34b90 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
34ba0 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
34bb0 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
34bc0 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
34bd0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
34be0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
34bf0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
34c00 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
34c10 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
34c20 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
34c30 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
34c40 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
34c50 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
34c60 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
34c70 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
34c80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
34c90 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
34ca0 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
34cb0 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
34cc0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34cd0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
34ce0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
34cf0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
34d00 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
34d10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
34d20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34d30 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
34d40 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
34d50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34d60 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
34d70 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
34d80 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
34d90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
34da0 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
34db0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
34dc0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
34dd0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
34de0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
34df0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
34e00 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
34e10 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
34e20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
34e30 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
34e40 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
34e50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
34e60 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
34e70 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
34e80 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
34e90 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
34ea0 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
34eb0 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
34ec0 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
34ed0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34ee0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
34ef0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
34f00 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
34f10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
34f20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34f30 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
34f40 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
34f50 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
34f60 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
34f70 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
34f80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34f90 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
34fa0 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
34fb0 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
34fc0 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
34fd0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
34fe0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
34ff0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
35000 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
35010 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
35020 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
35030 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
35040 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
35050 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
35060 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
35070 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
35080 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
35090 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
350a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
350b0 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
350c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
350d0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ded16()]..*/.SQL
350e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
350f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35100 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
35110 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
35120 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
35130 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
35140 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
35150 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
35160 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
35170 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
35180 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
35190 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
351a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
351b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
351c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
351d0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
351e0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
351f0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
35200 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
35210 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
35220 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
35230 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35240 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
35250 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
35260 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
35270 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35280 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
35290 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
352a0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
352b0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
352c0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
352d0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
352e0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
352f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
35300 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
35310 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
35320 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
35330 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
35340 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
35350 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
35360 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
35370 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
35380 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
35390 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
353a0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
353b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
353c0 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
353d0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
353e0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
353f0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
35400 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
35410 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
35420 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
35430 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
35440 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35450 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
35460 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
35470 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
35480 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
35490 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
354a0 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
354b0 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
354c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
354d0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
354e0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
354f0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
35500 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
35510 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
35520 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
35530 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
35540 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
35550 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
35560 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
35570 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
35580 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
35590 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
355a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
355b0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
355c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
355d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
355e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
355f0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
35600 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35610 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
35620 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
35630 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
35640 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
35650 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
35660 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
35670 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
35680 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
35690 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
356a0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
356b0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
356c0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
356d0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
356e0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
356f0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
35700 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
35710 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
35720 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
35730 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
35740 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
35750 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
35760 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
35770 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
35780 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
35790 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
357a0 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
357b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
357c0 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
357d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
357e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
357f0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
35800 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
35810 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
35820 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
35830 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
35840 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
35850 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
35860 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49  t char*).);.SQLI
35870 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
35880 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35890 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
358a0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
358b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
358c0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
358d0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
358e0 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
358f0 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
35900 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
35910 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
35920 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
35930 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
35940 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
35950 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
35960 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
35970 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
35980 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
35990 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
359a0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
359b0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
359c0 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
359d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  PI int sqlite3_k
359e0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
359f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
35a00 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
35a10 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
35a20 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
35a30 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
35a40 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
35a50 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
35a60 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
35a70 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
35a80 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
35a90 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
35aa0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
35ab0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
35ac0 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
35ad0 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
35ae0 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
35af0 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
35b00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
35b10 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
35b20 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
35b30 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
35b40 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
35b50 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
35b60 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
35b70 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
35b80 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
35b90 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35ba0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
35bb0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
35bc0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
35bd0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
35be0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
35bf0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
35c00 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
35c10 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
35c20 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
35c30 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
35c40 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
35c50 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
35c60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
35c70 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
35c80 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
35c90 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
35ca0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
35cb0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
35cc0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
35cd0 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
35ce0 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
35cf0 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
35d00 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
35d10 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
35d20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
35d30 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
35d40 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
35d50 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
35d60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35d70 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
35d80 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
35d90 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
35da0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
35db0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
35dc0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
35dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
35de0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
35df0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
35e00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35e10 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
35e20 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
35e30 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
35e40 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
35e50 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
35e60 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
35e70 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
35e80 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
35e90 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
35ea0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
35eb0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
35ec0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
35ed0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
35ee0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
35ef0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
35f00 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
35f10 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
35f20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
35f30 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
35f40 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
35f50 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
35f60 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
35f70 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
35f80 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
35f90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
35fa0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
35fb0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
35fc0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
35fd0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
35fe0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
35ff0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
36000 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
36010 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
36020 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
36030 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
36040 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
36050 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
36060 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
36070 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
36080 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
36090 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
360a0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
360b0 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
360c0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
360d0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
360e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65   int sqlite3_sle
360f0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
36100 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
36110 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
36120 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
36130 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
36140 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
36150 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
36160 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
36170 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
36180 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
36190 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
361a0 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
361b0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
361c0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
361d0 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
361e0 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
361f0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
36200 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
36210 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
36220 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
36230 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
36240 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36250 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
36260 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
36270 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
36280 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
36290 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
362a0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
362b0 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
362c0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
362d0 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
362e0 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
362f0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
36300 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
36310 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
36320 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
36330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36340 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
36350 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
36360 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
36370 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
36380 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
36390 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
363a0 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
363b0 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
363c0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
363d0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
363e0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
363f0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
36400 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
36410 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
36420 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
36430 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
36440 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
36450 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36460 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36470 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
36480 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
36490 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
364a0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
364b0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
364c0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
364d0 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
364e0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
364f0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36500 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
36510 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
36520 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
36530 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
36540 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
36550 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36560 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
36570 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
36580 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
36590 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
365a0 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
365b0 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
365c0 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
365d0 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
365e0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
365f0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
36600 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
36610 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
36620 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
36630 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
36640 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
36650 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
36660 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36670 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36680 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
36690 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
366a0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
366b0 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
366c0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
366d0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
366e0 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
366f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
36700 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69  3_open] or [sqli
36710 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f  te3_open_v2].  O
36720 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
36730 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
36740 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
36750 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
36760 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20  files may fail. 
36770 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65   Here is an.** e
36780 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f  xample of how to
36790 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43   do this using C
367a0 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64  ++ with the Wind
367b0 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a  ows Runtime:.**.
367c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
367d0 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20  pre>.** LPCWSTR 
367e0 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a  zPath = Windows:
367f0 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63  :Storage::Applic
36800 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65  ationData::Curre
36810 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  nt->.** &nbsp;  
36820 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64     TemporaryFold
36830 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29  er->Path->Data()
36840 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42  ;.** char zPathB
36850 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20  uf&#91;MAX_PATH 
36860 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d  + 1&#93;;.** mem
36870 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c  set(zPathBuf, 0,
36880 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66   sizeof(zPathBuf
36890 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54  ));.** WideCharT
368a0 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54  oMultiByte(CP_UT
368b0 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31  F8, 0, zPath, -1
368c0 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65  , zPathBuf, size
368d0 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a  of(zPathBuf),.**
368e0 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c   &nbsp;     NULL
368f0 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69  , NULL);.** sqli
36900 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
36910 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  ry = sqlite3_mpr
36920 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68  intf("%s", zPath
36930 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  Buf);.** </pre><
36940 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a  /blockquote>.*/.
36950 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
36960 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
36970 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
36980 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
36990 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
369a0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
369b0 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  ng Database File
369c0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
369d0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
369e0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
369f0 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
36a00 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
36a10 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
36a20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
36a30 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74  y), then all dat
36a40 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73  abase files.** s
36a50 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20  pecified with a 
36a60 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
36a70 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72  e and created or
36a80 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20   accessed by.** 
36a90 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
36aa0 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e  g a built-in win
36ab0 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66  dows [sqlite3_vf
36ac0 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65  s | VFS] will be
36ad0 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62   assumed.** to b
36ae0 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68  e relative to th
36af0 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
36b00 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
36b10 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e is a NULL.** p
36b20 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
36b30 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
36b40 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69   all database fi
36b50 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  les specified.**
36b60 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65   with a relative
36b70 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65   pathname are re
36b80 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75  lative to the cu
36b90 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a  rrent directory.
36ba0 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65  ** for the proce
36bb0 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69  ss.  Only the wi
36bc0 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20  ndows VFS makes 
36bd0 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62  use of this glob
36be0 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20  al.** variable; 
36bf0 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79  it is ignored by
36c00 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a   the unix VFS..*
36c10 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68  *.** Changing th
36c20 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  e value of this 
36c30 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61  variable while a
36c40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36c50 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20  tion is.** open 
36c60 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20  can result in a 
36c70 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65  corrupt database
36c80 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
36c90 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
36ca0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
36cb0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
36cc0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
36cd0 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
36ce0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
36cf0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
36d00 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
36d10 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
36d20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
36d30 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
36d40 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
36d50 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
36d60 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
36d70 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
36d80 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
36d90 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
36da0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
36db0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
36dc0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
36dd0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
36de0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
36df0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
36e00 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
36e10 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
36e20 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
36e30 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74  ** ^The [data_st
36e40 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
36e50 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
36e60 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
36e70 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
36e80 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
36e90 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36ea0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
36eb0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
36ec0 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74  .** the [data_st
36ed0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
36ee0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
36ef0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
36f00 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
36f10 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
36f20 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
36f30 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
36f40 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
36f50 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
36f60 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
36f70 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
36f80 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
36f90 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
36fa0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
36fb0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
36fc0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
36fd0 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
36fe0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
36ff0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
37000 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
37010 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
37020 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
37030 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
37040 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74   of the [data_st
37050 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37060 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
37070 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
37080 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
37090 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
370a0 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f 72  e3_data_director
370b0 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
370c0 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
370d0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
370e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
370f0 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
37100 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37110 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
37120 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37130 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
37140 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
37150 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
37160 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
37170 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
37180 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
37190 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
371a0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
371b0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
371c0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
371d0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
371e0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
371f0 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
37200 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
37210 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
37220 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
37230 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
37240 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
37250 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
37260 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
37270 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
37280 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
37290 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
372a0 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
372b0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
372c0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
372d0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
372e0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
372f0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
37300 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
37310 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
37320 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
37330 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
37340 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
37350 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
37360 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
37370 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
37380 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
37390 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
373a0 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
373b0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
373c0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
373d0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
373e0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
373f0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
37400 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
37410 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
37420 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
37430 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
37440 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
37450 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
37460 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
37470 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
37480 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
37490 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
374a0 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
374b0 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
374c0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
374d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
374e0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
374f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
37500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37510 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
37520 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
37530 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
37540 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
37550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37560 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
37570 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
37580 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
37590 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
375a0 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
375b0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
375c0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
375d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
375e0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
375f0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
37600 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
37610 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
37620 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
37630 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c  st place..*/.SQL
37640 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
37650 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
37660 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
37670 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37680 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46  EF: Return The F
37690 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61  ilename For A Da
376a0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
376b0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
376c0 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
376d0 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
376e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
376f0 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a  r to a filename.
37700 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
37710 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66  th database N of
37720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
37730 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61  ^The main databa
37740 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74  se file.** has t
37750 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20  he name "main". 
37760 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
37770 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
37780 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62  e N on the datab
37790 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
377a0 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62  n D, or if datab
377b0 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f  ase N is a tempo
377c0 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72  rary or in-memor
377d0 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e  y database, then
377e0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
377f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
37800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e  **.** ^The filen
37810 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ame returned by 
37820 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
37830 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74   the output of t
37840 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e  he.** xFullPathn
37850 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ame method of th
37860 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74  e [VFS].  ^In ot
37870 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66  her words, the f
37880 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  ilename.** will 
37890 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  be an absolute p
378a0 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66  athname, even if
378b0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73   the filename us
378c0 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68  ed.** to open th
378d0 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69  e database origi
378e0 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20  nally was a URI 
378f0 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68  or relative path
37900 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  name..*/.SQLITE_
37910 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
37920 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
37930 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ame(sqlite3 *db,
37940 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
37950 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
37960 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
37970 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
37980 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a  is read-only.**.
37990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
379a0 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29  db_readonly(D,N)
379b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
379c0 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61  ns 1 if the data
379d0 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e  base N.** of con
379e0 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61  nection D is rea
379f0 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20  d-only, 0 if it 
37a00 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f  is read/write, o
37a10 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74  r -1 if N is not
37a20 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
37a30 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f  a database on co
37a40 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53  nnection D..*/.S
37a50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37a60 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
37a70 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
37a80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
37a90 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
37aa0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
37ab0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
37ac0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
37ad0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37ae0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37af0 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
37b00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37b10 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
37b20 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
37b30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37b40 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
37b50 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
37b60 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
37b70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37b80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37b90 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
37ba0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
37bb0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
37bc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37bd0 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
37be0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
37bf0 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
37c00 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
37c10 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
37c20 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
37c30 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
37c40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37c50 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
37c60 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
37c70 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
37c80 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
37c90 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
37ca0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37cb0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
37cc0 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
37cd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37ce0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
37cf0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
37d00 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
37d10 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
37d20 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
37d30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37d40 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
37d50 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
37d60 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
37d70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d80 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
37d90 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
37da0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
37db0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
37dc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
37dd0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
37de0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
37df0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
37e00 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
37e10 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
37e20 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
37e30 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
37e40 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
37e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37e60 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
37e70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
37e80 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
37e90 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37ea0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
37eb0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
37ec0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
37ed0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
37ee0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
37ef0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
37f00 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
37f10 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
37f20 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
37f30 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
37f40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
37f50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37f60 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
37f70 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
37f80 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
37f90 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
37fa0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
37fb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
37fc0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
37fd0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
37fe0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
37ff0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
38000 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
38010 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
38020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
38030 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
38040 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
38050 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
38060 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
38070 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
38080 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
38090 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
380a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
380b0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
380c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
380d0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
380e0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
380f0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
38100 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
38110 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61  .** The commit a
38120 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  nd rollback hook
38130 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e   callbacks are n
38140 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a  ot reentrant..**
38150 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
38160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
38170 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
38180 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
38190 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
381a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
381b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
381c0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
381d0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
381e0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
381f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
38200 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
38210 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
38220 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
38230 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
38240 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
38250 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
38260 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
38270 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
38280 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
38290 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e   that running an
382a0 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74  y other SQL stat
382b0 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  ements, includin
382c0 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  g SELECT stateme
382d0 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c  nts,.** or merel
382e0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
382f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
38300 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
38310 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66  ep()] will modif
38320 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
38330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
38340 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
38350 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
38360 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
38370 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
38380 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
38390 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
383a0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
383b0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
383c0 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
383d0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
383e0 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
383f0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
38400 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
38410 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
38420 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
38430 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
38440 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
38450 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
38460 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
38470 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
38480 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
38490 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
384a0 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
384b0 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
384c0 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
384d0 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
384e0 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
384f0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
38500 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
38510 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
38520 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
38530 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
38540 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
38550 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
38560 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
38570 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
38580 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
38590 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
385a0 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
385b0 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
385c0 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
385d0 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
385e0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
385f0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
38600 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
38610 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
38620 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
38630 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
38640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38650 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
38660 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
38670 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
38680 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
38690 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
386a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
386b0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
386c0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
386d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
386e0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
386f0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
38700 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
38710 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
38720 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
38730 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
38740 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
38750 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
38760 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
38770 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
38780 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
38790 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
387a0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with