System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact dc8173379eff60bc0fe0d49da643be4b4ddbb036:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 38 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.2".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 38 30 30 32 0a 23 64 65 66  BER 3008002.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 2d  E_ID      "2013-
1070: 31 31 2d 31 31 20 31 39 3a 35 36 3a 33 35 20 66  11-11 19:56:35 f
1080: 35 38 64 35 37 30 31 37 31 39 39 34 32 31 31 36  58d5701719942116
1090: 37 64 61 65 38 65 62 63 36 37 64 62 32 66 31 39  7dae8ebc67db2f19
10a0: 62 65 34 35 30 38 32 22 0a 0a 2f 2a 0a 2a 2a 20  be45082"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1c70: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1c80: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1c90: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1ca0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1cb0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1cc0: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1cd0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1ce0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1cf0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1d00: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1d10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1d20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1d30: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1d40: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1d50: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1d60: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1d70: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1d80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1d90: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1da0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1db0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1dc0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1dd0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1de0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1df0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1e00: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1e10: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1e20: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1e30: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1e40: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1e50: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1e60: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1e70: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
1e80: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
1e90: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
1ea0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
1eb0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
1ec0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
1ed0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
1ee0: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1ef0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
1f00: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
1f10: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
1f20: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f30: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
1f40: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
1f50: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
1f60: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
1f70: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
1f80: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
1f90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1fa0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
1fb0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
1fc0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fd0: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
1fe0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
1ff0: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2000: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2010: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
2020: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2030: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
2040: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2050: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2060: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
2070: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
2080: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
2090: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
20a0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
20b0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
20c0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
20d0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
20f0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2110: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
2120: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2130: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2150: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
2160: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2170: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
2180: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
2190: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
21a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
21b0: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
21c0: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
21d0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
21e0: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
21f0: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
2200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
2210: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2220: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2230: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
2240: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
2250: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
2260: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2270: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
2280: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
2290: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
22a0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
22b0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
22c0: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
22d0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
22e0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
22f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2300: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2310: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
2320: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
2330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
2340: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2350: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
2360: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
2370: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
2380: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
2390: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
23a0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
23b0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
23c0: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
23d0: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
23e0: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
23f0: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
2400: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
2410: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2420: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2430: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
2440: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2450: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
2460: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
2470: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
2480: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
2490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
24a0: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
24b0: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
24c0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
24d0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
24e0: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
24f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2500: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2510: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2530: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
2540: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
2550: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
2560: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
2570: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
2580: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2590: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
25a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25b0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
25c0: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
25d0: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
25e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
25f0: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
2600: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
2610: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
2620: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
2630: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
2640: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
2650: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
2660: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
2670: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
2680: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2690: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
26a0: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
26b0: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
26c0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
26d0: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
26e0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
26f0: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
2700: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
2710: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
2720: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
2730: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2740: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2750: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
2760: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2770: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
2780: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
2790: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
27a0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
27b0: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
27c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
27d0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
27e0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
27f0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2800: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
2810: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
2820: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
2830: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
2840: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2850: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
2860: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2870: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2880: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
2890: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28b0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
28c0: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
28d0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
28e0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
28f0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2900: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2910: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2920: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2930: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2940: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2950: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2960: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2970: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2980: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2990: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
29a0: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
29b0: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
29c0: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
29d0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
29e0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
29f0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2a00: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2a10: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2a20: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2a30: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2a40: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2a50: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2a60: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2a70: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2a80: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2a90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2aa0: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2ab0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2ac0: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
2ad0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2ae0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2af0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2b00: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2b10: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2b20: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2b30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b40: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2b50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2b60: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
2b70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2b80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2b90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ba0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2bb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2bc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2bd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2be0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2bf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2c00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2c10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2c20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2c30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2c40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2c50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2c60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2c70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2c80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2c90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2ca0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2cb0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2cc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2cd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2ce0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cf0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69  ents.** and unfi
2d00: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2d10: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
2d20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d30: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
2d40: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
2d50: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
2d60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
2d70: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
2d80: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
2d90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da0: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
2db0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
2dc0: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
2dd0: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
2de0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2df0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
2e00: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
2e10: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
2e20: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
2e30: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
2e40: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
2e50: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
2e60: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
2e70: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
2e80: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
2e90: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2eb0: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
2ec0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
2ed0: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
2ee0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2ef0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2f00: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
2f10: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
2f20: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
2f30: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
2f40: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2f50: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
2f60: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
2f70: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
2f80: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
2f90: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
2fa0: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
2fb0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2fc0: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
2fd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fe0: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
2ff0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
3000: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
3010: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
3020: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
3030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3040: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
3050: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c  n it returns SQL
3060: 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64  ITE_OK but the d
3070: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3080: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3090: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
30a0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
30b0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
30c0: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
30d0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30e0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
30f0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3100: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3110: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3120: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3130: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
3140: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
3150: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3160: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3170: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3180: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3190: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
31a0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31b0: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
31c0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
31d0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
31e0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
31f0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3200: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3210: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3220: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3230: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
3240: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
3250: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3260: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3270: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3280: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3290: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
32a0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
32b0: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
32c0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
32d0: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
32e0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
32f0: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
3300: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
3310: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3320: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3330: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3340: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3350: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
3360: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
3370: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
3380: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
3390: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
33a0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
33b0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
33c0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
33d0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
33e0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
33f0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3400: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3410: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3420: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
3430: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3440: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3450: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
3460: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
3470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
3480: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
3490: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
34a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34b0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
34c0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
34d0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
34e0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
34f0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
3500: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
3510: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
3520: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3530: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3540: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
3550: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
3560: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
3570: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
3580: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3590: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
35a0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
35b0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
35c0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35d0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
35e0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
35f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
3600: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3610: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
3620: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3630: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3640: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3650: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
3660: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
3670: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
3680: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
3690: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
36a0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
36b0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
36c0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
36d0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
36e0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
36f0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
3700: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
3710: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3720: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3740: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
3750: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
3760: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
3770: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
3780: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
3790: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
37a0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
37b0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
37c0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
37d0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
37e0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
37f0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
3800: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
3810: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
3820: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
3830: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
3840: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3850: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3860: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
3870: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
3880: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
3890: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
38a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
38b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38c0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
38d0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
38e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
38f0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
3900: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
3910: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
3920: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
3930: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
3940: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
3950: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
3960: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
3970: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
3980: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
3990: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
39a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
39b0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
39c0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
39d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
39f0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3a00: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3a10: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3a20: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3a30: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3a40: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3a50: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3a60: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3a70: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3a80: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3a90: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3aa0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3ab0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3ac0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3ad0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3ae0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3af0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3b00: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3b10: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3b20: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3b30: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3b40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3b60: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3b70: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3b80: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3b90: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3ba0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3bb0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3bc0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3bd0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3be0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3bf0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3c00: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3c10: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3c20: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3c30: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3c40: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3c50: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3c60: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3c70: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3c80: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3c90: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3ca0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3cb0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3cc0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3cd0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3ce0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3cf0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3d00: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3d10: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3d20: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3d30: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3d40: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3d50: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3d60: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3d70: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3d80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3d90: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3da0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3db0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3dc0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3dd0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3de0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3df0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3e00: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3e10: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3e20: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3e30: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3e40: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3e50: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3e60: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3e70: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
3e80: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
3e90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
3ea0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3eb0: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
3ec0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
3ef0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
3f00: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
3f10: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
3f20: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f30: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
3f40: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3f50: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3f60: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3f70: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f80: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f90: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3fa0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3fb0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3fc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3fd0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3fe0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3ff0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
4000: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
4010: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
4020: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
4040: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
4050: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
4060: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
4070: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  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: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
40b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
40c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
40f0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
4100: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
4110: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
4120: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
4130: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
4140: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 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: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
4180: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
4190: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 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 2f 2a 20 45              /* E
41c0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
41d0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
41e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
41f0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4200: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
4210: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
4220: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
4250: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
4260: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
4270: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
4280: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
4290: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
42a0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
42b0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
42c0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
42d0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
42e0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
42f0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
4300: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4310: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
4320: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
4330: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
4340: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4350: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
4360: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
4370: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
4380: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
4390: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
43a0: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
43b0: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
43c0: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
43d0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
43e0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
43f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
4400: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
4410: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
4420: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
4430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4440: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
4450: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
4460: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
4470: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
4480: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
4490: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
44a0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
44b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
44c0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
44d0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
44e0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
44f0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
4510: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
4520: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4530: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
4540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4550: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
4560: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
4570: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
4580: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4590: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
45a0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
45b0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
45e0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
45f0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
4600: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4620: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
4630: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
4640: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
4650: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4670: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
4680: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
4690: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
46a0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
46b0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
46c0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
46d0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
46e0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
4710: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
4720: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
4730: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4760: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4770: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4780: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
47b0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
47c0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
47d0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
47e0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
47f0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
4800: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
4810: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
4830: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
4840: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4850: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4860: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4870: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4880: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4890: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
48a0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
48b0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
48c0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
48d0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
48f0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
4900: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
4910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
4920: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
4930: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
4940: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4950: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4970: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4980: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4990: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
49b0: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
49c0: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
49d0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
49e0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
4a00: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
4a10: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
4a20: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4a30: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
4a40: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4a50: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4a60: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4a80: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4a90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4aa0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4ab0: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4ad0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4ae0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4af0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4b00: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
4b20: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
4b30: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
4b40: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b60: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
4b70: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
4b80: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4b90: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4ba0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4bb0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4bc0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4bd0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4bf0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4c00: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c10: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4c20: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4c30: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4c40: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4c50: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4c60: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4c70: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4c80: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
4c90: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4ca0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4cb0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4cc0: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ult code} {exten
4cd0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ce0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
4cf0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
4d00: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4d10: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4d20: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4d30: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4d40: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4d50: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4d60: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4d70: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4d80: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4d90: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4da0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4db0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4dc0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4dd0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4de0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4df0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e00: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e10: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e20: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e30: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e40: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4e50: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4e60: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4e70: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4e80: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4e90: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4ea0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4eb0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4ec0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
4ed0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
4ee0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4ef0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4f00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4f10: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4f20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4f30: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4f40: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20  s()] API..**.** 
4f50: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
4f60: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
4f70: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4f80: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20  listed here..** 
4f90: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74  One may expect t
4fa0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
4fb0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4fc0: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
4fd0: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
4fe0: 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75   Software that u
4ff0: 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  ses extended res
5000: 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64  ult codes should
5010: 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65   expect.** to se
5020: 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64  e new result cod
5030: 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
5040: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
5050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5060: 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65  E_OK result code
5070: 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65   will never be e
5080: 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c  xtended.  It wil
5090: 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65  l always.** be e
50a0: 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a  xactly zero..*/.
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50c0: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5120: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5240: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5260: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
5280: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
52c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5300: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5320: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
5340: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5360: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
5380: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53a0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
53c0: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
53d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
53f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
5400: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5420: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b  QLITE_IOERR_LOCK
5440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5460: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53  QLITE_IOERR_CLOS
5480: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
5490: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54a0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
54b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
54c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53  CLOSE         (S
54d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54e0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
54f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f  QLITE_IOERR_SHMO
5500: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53  PEN           (S
5510: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5520: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5530: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53  QLITE_IOERR_SHMS
5540: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53  IZE           (S
5550: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5560: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5570: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c  QLITE_IOERR_SHML
5580: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53  OCK           (S
5590: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55a0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
55b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d  QLITE_IOERR_SHMM
55c0: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AP            (S
55d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
55f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b  QLITE_IOERR_SEEK
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5610: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5620: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5630: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5640: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53  TE_NOENT      (S
5650: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5660: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5670: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50  QLITE_IOERR_MMAP
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5690: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56a0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
56b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54  QLITE_IOERR_GETT
56c0: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53  EMPPATH       (S
56d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56e0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
56f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56  QLITE_IOERR_CONV
5700: 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53  PATH          (S
5710: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5720: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5730: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41  QLITE_LOCKED_SHA
5740: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53  REDCACHE      (S
5750: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20  QLITE_LOCKED |  
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 42 55 53 59 5f 52 45 43 4f  SQLITE_BUSY_RECO
5780: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28  VERY           (
5790: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41   SQLITE_BUSY_SNA
57c0: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20  PSHOT           
57d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
57e0: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (2<<8)).#defin
57f0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5800: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5810: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5820: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
5830: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5840: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
5850: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5860: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
5870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5880: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
5890: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58a0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
58b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58c0: 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48  ANTOPEN_CONVPATH
58d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
58e0: 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29  ANTOPEN | (4<<8)
58f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5900: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
5910: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5920: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
5930: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5940: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5950: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5960: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5970: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5980: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5990: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
59a0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
59c0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
59d0: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53  OLLBACK       (S
59e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
59f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5a00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a10: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a20: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a50: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a70: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a90: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5aa0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ab0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ad0: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5ae0: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b20: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ba0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5bb0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bc0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5be0: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5bf0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c30: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c50: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c70: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5c80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c90: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5cb0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5cd0: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5cf0: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d00: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d10: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d30: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d40: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d50: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5d70: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5d80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5d90: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5da0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5db0: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5dc0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5dd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5de0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5df0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5e00: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5e10: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5e20: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5e30: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5e40: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5e50: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5e70: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5ea0: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5eb0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5ec0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ee0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5ef0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5f00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f30: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5f40: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5f50: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f60: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f80: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5f90: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5fa0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5fb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fc0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5fd0: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5fe0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6000: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
6010: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
6020: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6040: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
6050: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
6060: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6070: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6080: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6090: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
60a0: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
60b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
60c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
60d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
60e0: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
60f0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
6100: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6110: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6120: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
6130: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
6140: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6150: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6160: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
6170: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
6180: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6190: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
61a0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
61b0: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
61c0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
61d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
61e0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
61f0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
6200: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6210: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6220: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
6230: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
6240: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6250: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6260: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
6270: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
6280: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6290: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
62a0: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
62b0: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
62c0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
62d0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
62e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
62f0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
6300: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
6310: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6320: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6330: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6340: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6350: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6360: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6370: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6380: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6390: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
63a0: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
63b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
63c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
63d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
63e0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
63f0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
6400: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
6410: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
6440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6450: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6460: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6470: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6480: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6490: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
64a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
64b0: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
64c0: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
64d0: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
64e0: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
64f0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
6500: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
6510: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
6520: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
6530: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
6540: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6550: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6560: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6570: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6580: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6590: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
65a0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
65b0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
65c0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
65d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
65e0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
65f0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6600: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6610: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6620: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
6630: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6640: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6650: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6660: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6670: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6680: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6690: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
66a0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
66b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
66c0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
66d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
66e0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
66f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6700: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6710: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6720: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
6730: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6740: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6750: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6760: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6770: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6780: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6790: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
67a0: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
67b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
67c0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
67d0: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
67e0: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
67f0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
6800: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
6810: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
6820: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
6830: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
6840: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6850: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6860: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6870: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6880: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6890: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
68a0: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
68b0: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
68c0: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
68d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
68e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6900: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6910: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6920: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6930: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6940: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6950: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6970: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6980: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6990: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
69a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
69b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
69d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69e0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
69f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a00: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6a10: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a30: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6a40: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a50: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6a60: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a70: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6a80: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6a90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6aa0: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6ab0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ac0: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6ad0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6ae0: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6af0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6b00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b10: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6b20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6b30: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b40: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6b50: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6b60: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6b70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6b80: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6b90: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6ba0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6bb0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6bc0: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6bd0: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6be0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6bf0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6c00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6c10: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6c20: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
6c30: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
6c40: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6c50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6c60: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c80: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ca0: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6cb0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6cc0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6cd0: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6ce0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
6cf0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
6d00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6d10: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
6d20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6d30: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
6d40: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6d50: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6d60: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6d70: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6d80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6d90: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6da0: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6db0: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6dc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6dd0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6de0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6df0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6e00: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6e10: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6e20: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6e30: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6e40: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6e50: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6e60: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6e70: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6e80: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6e90: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6ea0: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6eb0: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6ec0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ed0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6ee0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6ef0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6f00: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6f10: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6f20: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6f30: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6f40: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6f50: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6f60: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6f70: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6f80: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6f90: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6fa0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6fb0: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6fc0: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6fd0: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6fe0: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6ff0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
7000: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
7010: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7020: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
7030: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
7040: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
7050: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
7060: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
7070: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
7080: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
7090: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
70a0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
70b0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
70c0: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
70d0: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
70e0: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
70f0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
7100: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
7110: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7120: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
7130: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
7140: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
7150: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
7160: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7170: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
7180: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
7190: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
71a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
71b0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
71c0: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
71d0: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
71e0: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
71f0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
7200: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
7210: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7220: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
7230: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
7240: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7250: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
7260: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
7280: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
7290: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
72a0: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
72b0: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
72c0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
72d0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
72e0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
72f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7300: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7310: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7320: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7330: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
7340: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7350: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7360: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7370: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7380: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7390: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
73a0: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
73b0: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
73c0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
73d0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
73e0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
73f0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7400: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7410: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7420: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7430: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
7440: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7450: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7460: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7470: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7490: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
74a0: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
74b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
74c0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
74d0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
74e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
74f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7500: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7510: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7520: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7530: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
7540: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7550: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7560: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7570: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7580: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7590: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
75a0: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
75b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
75c0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
75d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
75e0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
75f0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7600: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7610: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7620: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7630: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
7640: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7650: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7660: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7670: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7680: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7690: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
76a0: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
76b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
76c0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
76d0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
76e0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
76f0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7700: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7710: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7720: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7730: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7740: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7750: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7760: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7770: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7780: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7790: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
77a0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
77b0: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
77c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
77d0: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
77e0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
77f0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7800: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7810: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7820: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
7830: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
7840: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7850: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7860: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7870: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7880: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7890: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
78a0: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
78b0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
78c0: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
78d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
78e0: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
78f0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7900: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7910: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7920: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
7930: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
7940: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7950: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7960: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7970: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7980: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7990: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
79a0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
79b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
79c0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
79d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
79e0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
79f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a00: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7a10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a20: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
7a30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
7a40: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7a50: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7a60: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7a70: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7a80: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7a90: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7aa0: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7ab0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7ac0: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7ad0: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7ae0: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7af0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7b00: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7b10: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7b20: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
7b30: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
7b40: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7b50: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7b60: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7b70: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7b80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7b90: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7ba0: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7bb0: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7bc0: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7bd0: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7be0: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7bf0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7c00: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7c10: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7c20: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
7c30: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
7c40: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7c50: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7c60: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7c70: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7c80: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7c90: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7ca0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7cb0: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7cc0: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7cd0: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7ce0: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
7cf0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
7d00: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
7d10: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
7d20: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
7d30: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
7d40: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7d50: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7d60: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7d70: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7d80: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7d90: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7da0: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7db0: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7dc0: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7dd0: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7de0: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7df0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7e00: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7e10: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7e20: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7e30: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7e40: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7e50: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7e60: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7e70: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7e80: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7e90: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7ea0: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7eb0: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7ec0: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7ed0: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7ee0: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7ef0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7f00: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7f10: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7f20: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7f30: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7f40: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7f50: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7f60: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7f70: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7f80: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7f90: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7fa0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7fb0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7fc0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7fd0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7fe0: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7ff0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
8000: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
8010: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
8020: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
8030: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
8040: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8050: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
8060: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
8070: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
8080: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
8090: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
80a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
80b0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
80c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80d0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
80e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
80f0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
8120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8130: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
8140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8150: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
8160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8170: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
8180: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8190: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
81a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
81c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
81d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
81e0: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
81f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
8200: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
8210: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
8220: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
8230: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
8240: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
8250: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
8260: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8270: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
8280: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
8290: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
82a0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
82b0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
82c0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
82d0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
82e0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
82f0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
8300: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
8310: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8320: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8330: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
8340: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8350: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8360: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8370: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8380: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8390: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
83a0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
83b0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
83c0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
83d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
83e0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
83f0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
8400: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
8410: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
8420: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
8430: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
8440: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8450: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8460: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8470: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8480: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8490: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
84a0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
84b0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
84c0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
84d0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
84e0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
84f0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
8500: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
8510: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
8520: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8530: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
8540: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8550: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8560: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8570: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8580: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8590: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
85a0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
85b0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
85c0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
85d0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
85e0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
85f0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
8600: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
8610: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8620: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8630: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
8640: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8650: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8660: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8670: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8680: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8690: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
86a0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
86b0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
86c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
86d0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
86e0: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
86f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8700: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
8710: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
8720: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8730: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
8740: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8750: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8760: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8770: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8780: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8790: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
87a0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
87b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
87c0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
87d0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
87e0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
87f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
8800: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8810: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
8820: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
8830: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8840: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8850: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8860: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8870: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8880: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8890: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
88a0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
88b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
88c0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
88d0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
88e0: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
88f0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8910: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8920: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
8930: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
8940: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8950: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8960: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8970: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8980: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8990: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
89a0: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
89b0: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
89c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
89d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
89e0: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
89f0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8a00: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8a10: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
8a20: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
8a30: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
8a40: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8a50: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8a60: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8a70: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8a80: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
8a90: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8aa0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8ab0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8ac0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8ad0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8ae0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8af0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8b00: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8b10: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8b20: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
8b30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8b40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8b50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8b60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8b70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8b80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8ba0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8bb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8bc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8bd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8be0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8bf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8c00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8c10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8c20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8c30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8c40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8c50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8c60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8c70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8c80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8c90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8ca0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8cb0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8cc0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8cd0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8ce0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8cf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8d00: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8d10: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8d20: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8d30: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8d40: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8d50: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8d60: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8d70: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8d80: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8d90: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8da0: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8db0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8dc0: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8dd0: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8de0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8df0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8e00: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8e10: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8e20: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8e30: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8e40: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8e50: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8e60: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8e70: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8e80: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8e90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8ea0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8eb0: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8ec0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8ed0: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8ee0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8ef0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8f00: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8f10: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8f20: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8f30: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8f40: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8f50: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8f60: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8f80: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8f90: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8fa0: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8fb0: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8fc0: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8fd0: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8fe0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8ff0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
9000: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
9010: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
9020: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
9030: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9040: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9050: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
9060: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
9070: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
9080: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9090: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
90a0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
90b0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
90c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
90d0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
90e0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
90f0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9100: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9110: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9120: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
9130: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9140: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9150: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
9160: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9170: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
9180: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
9190: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
91a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
91b0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
91c0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
91d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
91e0: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
91f0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9200: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
9210: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
9220: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
9230: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
9240: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
9250: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
9260: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
9270: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
9280: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
9290: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
92a0: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
92b0: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
92c0: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
92d0: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
92e0: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
92f0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9300: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9310: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
9320: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
9330: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
9340: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
9350: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
9360: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9370: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
9380: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9390: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
93a0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
93b0: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
93c0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
93d0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
93e0: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
93f0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9400: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
9410: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9420: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9430: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9440: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9450: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9460: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9470: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9480: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9490: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
94a0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
94b0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
94c0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
94d0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
94e0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
94f0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9500: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9510: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9520: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9530: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9540: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9550: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9560: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9570: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9580: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9590: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
95a0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
95b0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
95c0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
95d0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
95e0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
95f0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9600: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9610: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9620: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9630: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9640: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9650: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9660: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9670: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9680: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9690: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
96a0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
96b0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
96c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
96d0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
96e0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
96f0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9700: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9710: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9720: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9730: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9740: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9750: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9760: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9770: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9780: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9790: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
97a0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
97b0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
97c0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
97d0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
97e0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
97f0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9800: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9810: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9820: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9830: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9840: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9850: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9860: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9870: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9880: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9890: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
98a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
98b0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
98c0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
98d0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
98e0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
98f0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9900: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9910: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9920: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9930: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9940: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9950: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9960: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9970: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9980: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9990: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
99a0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
99b0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
99c0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
99d0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
99e0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
99f0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9a00: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9a10: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9a20: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9a30: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9a40: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9a50: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9a60: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9a70: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9a80: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9a90: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9aa0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9ab0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ac0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ad0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9ae0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9af0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9b00: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9b10: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9b20: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9b30: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9b40: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9b50: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9b60: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9b70: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9b80: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9b90: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9ba0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9bb0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9bc0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9bd0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9be0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9bf0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9c00: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9c10: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9c20: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9c30: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9c40: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9c50: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9c60: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9c70: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9c80: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9c90: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9ca0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9cb0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9cc0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9cd0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9ce0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9cf0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9d00: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9d10: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9d20: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9d30: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9d40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9d50: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9d60: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9d70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9d80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9d90: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9da0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9db0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9dc0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9dd0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9de0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9df0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9e00: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
9e10: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e20: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e30: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e40: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9e50: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9e60: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9e70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9e80: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9e90: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9ea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9eb0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9ec0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9ed0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9ee0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
9ef0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
9f00: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
9f10: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
9f20: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
9f30: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
9f40: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9f50: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9f60: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9f70: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9f80: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9f90: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
9fa0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
9fb0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9fc0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
9fd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9fe0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
9ff0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a000: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a010: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a020: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a030: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a040: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a050: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a060: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a070: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a080: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a090: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a0a0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a0b0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a0c0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a0d0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a0e0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a0f0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a100: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a110: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a120: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a130: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a140: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a150: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a160: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a170: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a180: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a190: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a1a0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a1b0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a1c0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a1d0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a1e0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a1f0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a200: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a210: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a220: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a230: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a240: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a250: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a260: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a270: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a280: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a290: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a2a0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a2b0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a2c0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a2d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a2e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a2f0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a300: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a310: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a320: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a330: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a340: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a350: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a360: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a370: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a380: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a390: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a3a0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a3b0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a3c0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a3d0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a3e0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a3f0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a400: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a410: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a420: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a430: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a440: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a450: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a460: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a470: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a480: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a490: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a4a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a4b0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a4c0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a4d0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a4e0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a4f0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a500: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a510: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a520: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a530: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a540: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a550: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a560: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a570: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a580: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a590: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a5a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a5b0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a5c0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a5d0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a5e0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a5f0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a600: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a610: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a620: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a630: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a640: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a650: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a660: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a670: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a680: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a690: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a6a0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a6b0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a6c0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a6d0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a6e0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a6f0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a700: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a710: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a720: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a730: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a740: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a750: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a760: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
a770: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
a780: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
a790: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
a7a0: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
a7b0: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
a7c0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
a7d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a7e0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a7f0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
a800: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
a810: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
a820: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
a830: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
a840: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
a850: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
a860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
a870: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a880: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a890: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a8a0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
a8b0: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
a8c0: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
a8d0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
a8e0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
a8f0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
a900: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
a910: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
a920: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
a930: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
a940: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
a950: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
a960: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
a970: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
a980: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
a990: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
a9a0: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
a9b0: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
a9c0: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
a9d0: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
a9e0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
a9f0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
aa00: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aa10: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
aa20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
aa30: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
aa40: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
aa50: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
aa60: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
aa70: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
aa80: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
aa90: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
aaa0: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
aab0: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
aac0: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
aad0: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
aae0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
aaf0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ab00: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ab10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
ab20: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
ab30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab40: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ab50: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
ab60: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ab70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ab80: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ab90: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
aba0: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
abb0: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
abc0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
abd0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
abe0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
abf0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ac00: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
ac10: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
ac20: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
ac30: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
ac40: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
ac50: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
ac60: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
ac70: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
ac80: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
ac90: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
aca0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
acb0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
acc0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
acd0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
ace0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
acf0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
ad00: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
ad10: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
ad20: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ad30: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
ad40: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
ad50: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
ad60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ad70: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
ad80: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
ad90: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
ada0: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
adb0: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
adc0: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
add0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
ade0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
adf0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
ae00: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
ae10: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
ae20: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
ae30: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
ae40: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
ae50: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
ae60: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
ae70: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
ae80: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
ae90: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
aea0: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
aeb0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
aec0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
aed0: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
aee0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
aef0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
af00: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
af10: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
af20: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
af30: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
af40: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
af50: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
af60: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
af70: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
af80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
af90: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
afa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
afb0: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
afc0: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
afd0: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
afe0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
aff0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b000: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b010: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b020: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b030: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b040: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b050: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b060: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b070: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b080: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b090: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b0a0: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b0b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b0c0: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b0d0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b0e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b0f0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b100: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b110: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b120: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b130: 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  **.** </ul>.*/.#
b140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b150: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
b160: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
b170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
b180: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b190: 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
b1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
b1b0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b1c0: 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
b1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
b1e0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
b1f0: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
b200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b210: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
b220: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
b230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
b240: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
b250: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
b260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
b270: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
b280: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
b290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b2a0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
b2b0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
b2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
b2d0: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
b2e0: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
b300: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
b310: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
b320: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
b330: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
b340: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
b350: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
b360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b370: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
b380: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
b390: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
b3a0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
b3d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b3e0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b3f0: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
b400: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b410: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b420: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
b430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b440: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
b450: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
b460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b470: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
b480: 20 20 20 20 20 20 20 20 20 20 31 39 0a 0a 2f 2a            19../*
b490: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
b4a0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
b4b0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
b4c0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
b4d0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
b4e0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
b4f0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
b500: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
b510: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
b520: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
b530: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
b540: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
b550: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
b560: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
b570: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
b580: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
b590: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
b5a0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
b5b0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
b5c0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
b5d0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
b5e0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
b5f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
b600: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
b610: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
b620: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
b630: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
b640: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
b650: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
b660: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
b670: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
b680: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
b690: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
b6a0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
b6b0: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
b6c0: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
b6d0: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
b6e0: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
b6f0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
b700: 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20  m".  See.** the 
b710: 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d  [VFS | VFS docum
b720: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75  entation] for fu
b730: 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f  rther informatio
b740: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  n..**.** The val
b750: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
b760: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
b770: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
b780: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
b790: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
b7a0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
b7b0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
b7c0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
b7d0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
b7e0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
b7f0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
b800: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
b810: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
b820: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
b830: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
b840: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
b850: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
b860: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
b870: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
b880: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
b890: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
b8a0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
b8b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
b8c0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
b8d0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
b8e0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
b8f0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
b900: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
b910: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
b920: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
b930: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
b940: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
b950: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
b960: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
b970: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
b980: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
b990: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
b9a0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
b9b0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
b9c0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
b9d0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
b9e0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
b9f0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
ba00: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
ba10: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
ba20: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
ba30: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
ba40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
ba50: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
ba60: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
ba70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
ba80: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
ba90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
baa0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
bab0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
bac0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
bad0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
bae0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
baf0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
bb00: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
bb10: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
bb20: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
bb30: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
bb40: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
bb50: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
bb60: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
bb70: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
bb80: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bb90: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
bba0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
bbb0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
bbc0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
bbd0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
bbe0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
bbf0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
bc00: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
bc10: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bc20: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
bc30: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
bc40: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
bc50: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
bc60: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
bc70: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
bc80: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
bc90: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
bca0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
bcb0: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
bcc0: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
bcd0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
bce0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
bcf0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
bd00: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
bd10: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
bd20: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
bd30: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
bd40: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
bd50: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
bd60: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
bd70: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
bd80: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
bd90: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
bda0: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
bdb0: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
bdc0: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
bdd0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
bde0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
bdf0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
be00: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
be10: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
be20: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
be30: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
be40: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
be50: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
be60: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
be70: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
be80: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
be90: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
bea0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
beb0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
bec0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
bed0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
bee0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
bef0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
bf00: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
bf10: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
bf20: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
bf30: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
bf40: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
bf50: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
bf60: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
bf70: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
bf80: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
bf90: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
bfa0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
bfb0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
bfc0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
bfd0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
bfe0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
bff0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
c000: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
c010: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c020: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
c030: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
c040: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c050: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
c060: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
c070: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
c080: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
c090: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
c0a0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
c0b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c0c0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
c0d0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
c0e0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
c0f0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
c100: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
c110: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c120: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
c130: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
c140: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
c150: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
c160: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
c170: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c180: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c190: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
c1a0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
c1b0: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
c1c0: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
c1d0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c1e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
c1f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c200: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
c210: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c220: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
c230: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c240: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
c250: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
c270: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
c280: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
c290: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
c2a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c2b0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
c2c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c2d0: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
c2e0: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
c2f0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
c300: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
c310: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
c320: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
c330: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
c340: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
c350: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
c360: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
c370: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
c380: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
c390: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
c3a0: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
c3b0: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
c3c0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
c3d0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
c3e0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
c3f0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
c400: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
c410: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
c420: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
c430: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
c440: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
c450: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c460: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
c470: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
c480: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
c490: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
c4a0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
c4b0: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
c4c0: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
c4d0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
c4e0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
c4f0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
c500: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
c510: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
c520: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
c530: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
c540: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
c550: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
c560: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c570: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
c580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
c590: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
c5a0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
c5b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
c5c0: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
c5d0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
c5e0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
c5f0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
c600: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
c610: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c620: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
c630: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
c640: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
c650: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
c660: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
c670: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
c680: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
c690: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
c6a0: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
c6b0: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
c6c0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
c6d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
c6e0: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
c6f0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
c700: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
c710: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
c720: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
c730: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
c740: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
c750: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
c760: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
c770: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
c780: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
c790: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
c7a0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
c7b0: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
c7c0: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
c7d0: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
c7e0: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
c7f0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
c800: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
c810: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
c820: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
c830: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
c840: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
c850: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
c860: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
c870: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
c880: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
c890: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
c8a0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
c8b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c8c0: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
c8d0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
c8e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
c8f0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
c900: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
c910: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
c920: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
c930: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
c940: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
c950: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
c960: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
c970: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
c980: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
c990: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
c9a0: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
c9b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
c9c0: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
c9d0: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
c9e0: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
c9f0: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
ca00: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
ca10: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
ca20: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
ca30: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
ca40: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
ca50: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
ca60: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
ca70: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
ca80: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
ca90: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
caa0: 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
cab0: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
cac0: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
cad0: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
cae0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
caf0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
cb00: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
cb10: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
cb20: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
cb30: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
cb40: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
cb50: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
cb60: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
cb70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
cb80: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
cb90: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
cba0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
cbb0: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
cbc0: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
cbd0: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
cbe0: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
cbf0: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
cc00: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
cc10: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
cc20: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
cc30: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
cc40: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
cc50: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
cc60: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
cc70: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
cc80: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
cc90: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
cca0: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
ccb0: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
ccc0: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
ccd0: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
cce0: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
ccf0: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
cd00: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
cd10: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
cd20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
cd30: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
cd40: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
cd50: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
cd60: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
cd70: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
cd80: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
cd90: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
cda0: 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
cdb0: 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
cdc0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
cdd0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
cde0: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
cdf0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
ce00: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
ce10: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
ce20: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
ce30: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
ce40: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
ce50: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
ce60: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
ce70: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
ce80: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
ce90: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
cea0: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
ceb0: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
cec0: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
ced0: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
cee0: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
cef0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
cf00: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
cf10: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
cf20: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
cf30: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
cf40: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
cf50: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
cf60: 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
cf70: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
cf80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
cf90: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
cfa0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
cfb0: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
cfc0: 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
cfd0: 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
cfe0: 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
cff0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d000: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
d010: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
d020: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
d030: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20  mber multiplied 
d040: 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65  by 86400000 (the
d050: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
d060: 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61  seconds in .** a
d070: 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20   24-hour day).  
d080: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d090: 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e   use the xCurren
d0a0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d0b0: 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63  hod to get the c
d0c0: 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61  urrent.** date a
d0d0: 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20  nd time if that 
d0e0: 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61  method is availa
d0f0: 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e  ble (if iVersion
d100: 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65   is 2 or .** gre
d110: 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e  ater and the fun
d120: 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
d130: 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77   not NULL) and w
d140: 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a  ill fall back.**
d150: 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65   to xCurrentTime
d160: 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69  () if xCurrentTi
d170: 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61  meInt64() is una
d180: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  vailable..**.** 
d190: 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43  ^The xSetSystemC
d1a0: 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65  all(), xGetSyste
d1b0: 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65  mCall(), and xNe
d1c0: 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69  stSystemCall() i
d1d0: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
d1e0: 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65   not used by the
d1f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54   SQLite core.  T
d200: 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e  hese optional in
d210: 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
d220: 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65  vided.** by some
d230: 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69   VFSes to facili
d240: 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20  tate testing of 
d250: 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79  the VFS code. By
d260: 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20   overriding .** 
d270: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74  system calls wit
d280: 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65  h functions unde
d290: 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61  r its control, a
d2a0: 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61   test program ca
d2b0: 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61  n.** simulate fa
d2c0: 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63  ults and error c
d2d0: 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77  onditions that w
d2e0: 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62  ould otherwise b
d2f0: 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f  e difficult.** o
d300: 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  r impossible to 
d310: 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74  induce.  The set
d320: 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73   of system calls
d330: 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
d340: 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65  rridden.** varie
d350: 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74  s from one VFS t
d360: 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66  o another, and f
d370: 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20  rom one version 
d380: 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  of the same VFS 
d390: 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
d3a0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
d3b0: 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74  at use these int
d3c0: 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20  erfaces must be 
d3d0: 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79  prepared for any
d3e0: 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68  .** or all of th
d3f0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ese interfaces t
d400: 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72  o be NULL or for
d410: 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20   their behavior 
d420: 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f  to change.** fro
d430: 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
d440: 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c   the next.  Appl
d450: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f  ications must no
d460: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63  t attempt to acc
d470: 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68  ess.** any of th
d480: 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74  ese methods if t
d490: 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74  he iVersion of t
d4a0: 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74  he VFS is less t
d4b0: 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65  han 3..*/.typede
d4c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
d4d0: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
d4e0: 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  ;.typedef void (
d4f0: 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
d500: 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
d510: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
d520: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
d530: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
d540: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
d550: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
d560: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
d570: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
d580: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
d590: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
d5a0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
d5b0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
d5c0: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
d5d0: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
d5e0: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
d5f0: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
d600: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
d610: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
d620: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d630: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
d640: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
d650: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
d660: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
d670: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
d680: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
d690: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
d6a0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
d6b0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
d6c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d6d0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
d6e0: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
d6f0: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
d700: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
d710: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
d720: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d730: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d740: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
d750: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
d760: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d770: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d780: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
d790: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
d7a0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
d7b0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d7c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d7d0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
d7e0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
d7f0: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
d800: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d810: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
d820: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
d830: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
d840: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
d850: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
d860: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
d870: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
d880: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
d890: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
d8a0: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
d8b0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
d8c0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
d8d0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
d8e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d8f0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
d900: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
d910: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
d920: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
d930: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
d940: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
d950: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
d960: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
d970: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
d980: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
d990: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
d9a0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
d9b0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
d9c0: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
d9d0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
d9e0: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
d9f0: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
da00: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
da10: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
da20: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
da30: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
da40: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
da50: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
da60: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
da70: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
da80: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
da90: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
daa0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
dab0: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
dac0: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
dad0: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
dae0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
daf0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
db00: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
db10: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
db20: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
db30: 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
db40: 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65  yscall_ptr (*xGe
db50: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
db60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
db70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
db80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78   const char *(*x
db90: 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
dba0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
dbb0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
dbc0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
dbd0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
dbe0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
dbf0: 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
dc00: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
dc10: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
dc20: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
dc30: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
dc40: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
dc50: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
dc60: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
dc70: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
dc80: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
dc90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
dca0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
dcb0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
dcc0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
dcd0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
dce0: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
dcf0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
dd00: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
dd10: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
dd20: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
dd30: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
dd40: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
dd50: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
dd60: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
dd70: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
dd80: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
dd90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
dda0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
ddb0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
ddc0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
ddd0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
dde0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ddf0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
de00: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
de10: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
de20: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
de30: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
de40: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
de50: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
de60: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
de70: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
de80: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
de90: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
dea0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
deb0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
dec0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ded0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
dee0: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
def0: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
df00: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
df10: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
df20: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
df30: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
df40: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
df50: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
df60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
df70: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
df80: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
df90: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
dfa0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
dfb0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
dfc0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
dfd0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
dfe0: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
dff0: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
e000: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
e010: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
e020: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e030: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e040: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
e050: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e060: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
e070: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
e080: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
e090: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e0a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
e0b0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
e0c0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
e0d0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e0e0: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
e0f0: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
e100: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
e110: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
e120: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
e130: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
e140: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
e150: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
e160: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e170: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
e180: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
e190: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
e1a0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
e1b0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
e1c0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
e1d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e1e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e1f0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e200: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e210: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e220: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e230: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
e240: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e250: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
e260: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
e270: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
e280: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e290: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
e2a0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
e2b0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
e2c0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
e2d0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
e2e0: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
e2f0: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
e300: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
e310: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
e320: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
e330: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
e340: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
e350: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
e360: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
e370: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
e380: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
e390: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
e3a0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
e3b0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
e3c0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
e3d0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
e3e0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
e3f0: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
e400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e410: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
e420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e430: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
e440: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
e450: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
e460: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
e470: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
e480: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
e490: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
e4a0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
e4b0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
e4c0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
e4d0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
e4e0: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
e4f0: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
e500: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
e510: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
e520: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
e530: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
e540: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
e550: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
e560: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
e570: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
e580: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
e590: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
e5a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
e5b0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
e5c0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
e5d0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
e5e0: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
e5f0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
e600: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
e610: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
e620: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
e630: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
e640: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
e650: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
e660: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
e670: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
e680: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
e690: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
e6a0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
e6b0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
e6c0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
e6d0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
e6e0: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
e6f0: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
e700: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
e710: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
e720: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
e730: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
e740: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
e750: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
e760: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
e770: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e780: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
e790: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
e7a0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
e7b0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
e7c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
e7d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e7e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
e7f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
e800: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e810: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
e820: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
e830: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
e840: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
e850: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
e860: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
e870: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
e880: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
e890: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
e8a0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e8b0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
e8c0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
e8d0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
e8e0: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
e8f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
e900: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
e910: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e920: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
e930: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
e940: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e950: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
e960: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
e970: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
e980: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
e990: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e9a0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
e9b0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
e9c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e9d0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
e9e0: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
e9f0: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ea00: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ea10: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ea20: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ea30: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
ea40: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
ea50: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ea60: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ea70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
ea80: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
ea90: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
eaa0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
eab0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
eac0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
ead0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
eae0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
eaf0: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
eb00: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
eb10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
eb20: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
eb30: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
eb40: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
eb50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eb60: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
eb70: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
eb80: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
eb90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eba0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
ebb0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
ebc0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
ebd0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
ebe0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
ebf0: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
ec00: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
ec10: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
ec20: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
ec30: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
ec40: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
ec50: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
ec60: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
ec70: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
ec80: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
ec90: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
eca0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ecb0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
ecc0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
ecd0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
ece0: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
ecf0: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
ed00: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
ed10: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
ed20: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
ed30: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
ed40: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
ed50: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
ed60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ed70: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
ed80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
ed90: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
eda0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
edb0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
edc0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
edd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
ede0: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
edf0: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
ee00: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
ee10: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
ee20: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
ee30: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
ee40: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
ee50: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
ee60: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
ee70: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
ee80: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
ee90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
eea0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
eeb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
eec0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
eed0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
eee0: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
eef0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ef00: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ef10: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
ef20: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
ef30: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
ef40: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
ef50: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
ef60: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
ef70: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
ef80: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
ef90: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
efa0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
efb0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
efc0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
efd0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
efe0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
eff0: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
f000: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
f010: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f020: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
f030: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
f040: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
f050: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
f060: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
f070: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
f080: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
f090: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0a0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
f0b0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
f0c0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
f0d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
f0e0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f0f0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
f100: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
f110: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
f120: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
f130: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
f140: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
f150: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
f160: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
f170: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
f180: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
f190: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
f1a0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
f1b0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
f1c0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
f1d0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
f1e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
f1f0: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
f200: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
f210: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
f220: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
f230: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
f240: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f250: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
f260: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
f270: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f280: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f290: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
f2a0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
f2b0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
f2c0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
f2d0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
f2e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f2f0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
f300: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
f310: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
f320: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
f330: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f340: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
f350: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
f360: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
f370: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f380: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
f390: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
f3a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
f3b0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
f3c0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
f3d0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
f3e0: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
f3f0: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
f400: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
f410: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
f420: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
f430: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
f440: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
f450: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
f460: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
f470: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
f480: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f490: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
f4a0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
f4b0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
f4c0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f4d0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
f4e0: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
f4f0: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
f500: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f510: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
f520: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
f530: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
f540: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
f550: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
f560: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
f570: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
f580: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
f590: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
f5a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f5b0: 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  e(void);.SQLITE_
f5c0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
f5d0: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
f5e0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
f5f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
f600: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
f610: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
f620: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
f630: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
f640: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
f650: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
f660: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
f670: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
f680: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
f690: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
f6a0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
f6b0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
f6c0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
f6d0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
f6e0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
f6f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
f700: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
f710: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
f720: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
f730: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
f740: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
f750: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
f760: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
f770: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
f780: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
f790: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
f7a0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
f7b0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
f7c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f7d0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
f7e0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
f7f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
f800: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
f810: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
f820: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
f830: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
f840: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
f850: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
f860: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
f870: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
f880: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
f890: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
f8a0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
f8b0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
f8c0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
f8d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f8e0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
f8f0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
f900: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
f910: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
f920: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
f930: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
f940: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
f950: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
f960: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f970: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
f980: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
f990: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
f9a0: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
f9b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
f9c0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
f9d0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
f9e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
f9f0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
fa00: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
fa10: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
fa20: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
fa30: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
fa40: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
fa50: 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
fa60: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
fa70: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
fa80: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
fa90: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
faa0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
fab0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
fac0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
fad0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
fae0: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
faf0: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
fb00: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
fb10: 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
fb20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fb30: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
fb40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
fb50: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
fb60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
fb70: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
fb80: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
fb90: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
fba0: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
fbb0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
fbc0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
fbd0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51  ror code]..*/.SQ
fbe0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
fbf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
fc00: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
fc10: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fc20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
fc30: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
fc40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
fc50: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
fc60: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
fc70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
fc80: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
fc90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fca0: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
fcb0: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
fcc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fcd0: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
fce0: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
fcf0: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
fd00: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
fd10: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
fd20: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
fd30: 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
fd40: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
fd50: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
fd60: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
fd70: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
fd80: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
fd90: 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
fda0: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
fdb0: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
fdc0: 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
fdd0: 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
fde0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
fdf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
fe00: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
fe10: 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
fe20: 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
fe30: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
fe40: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
fe50: 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
fe60: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
fe70: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
fe80: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
fe90: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
fea0: 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
feb0: 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
fec0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
fed0: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
fee0: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
fef0: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
ff00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
ff10: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
ff20: 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
ff30: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
ff40: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
ff50: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
ff60: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
ff70: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
ff80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ff90: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
ffa0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
ffb0: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
ffc0: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
ffd0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
ffe0: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
fff0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
10000 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
10010 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
10020 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10030 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
10040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10050 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
10060 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
10070 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
10080 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
10090 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
100a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
100b0 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
100c0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
100d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
100e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
100f0 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
10100 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
10110 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
10120 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
10130 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
10140 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
10150 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
10160 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
10170 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
10180 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
10190 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
101a0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
101b0 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
101c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
101d0 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
101e0 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
101f0 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
10200 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
10210 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
10220 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
10230 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
10240 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
10250 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
10260 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
10270 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
10280 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
10290 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
102a0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
102b0 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
102c0 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
102d0 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
102e0 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
102f0 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10300 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10310 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
10320 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
10330 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
10340 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
10350 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
10360 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
10370 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
10380 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
10390 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
103a0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
103b0 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
103c0 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
103d0 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
103e0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
103f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
10400 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
10410 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
10420 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
10430 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
10440 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10450 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
10460 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
10470 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
10480 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
10490 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
104a0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
104b0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
104c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
104d0 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
104e0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
104f0 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
10500 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
10510 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
10520 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
10530 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
10540 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
10550 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
10560 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
10570 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
10580 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
10590 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
105a0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
105b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
105c0 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
105d0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
105e0 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
105f0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
10600 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
10610 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
10620 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
10630 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
10640 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
10650 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
10660 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
10670 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
10680 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
10690 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
106a0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
106b0 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
106c0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
106d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
106e0 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
106f0 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
10700 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
10710 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
10720 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
10730 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
10740 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
10750 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
10760 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
10770 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
10780 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
10790 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
107a0 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
107b0 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
107c0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
107d0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
107e0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
107f0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10800 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10810 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10820 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10830 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10840 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10850 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10860 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10870 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10880 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10890 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
108a0 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
108b0 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
108c0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
108d0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
108e0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
108f0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10900 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10910 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10920 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10930 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10940 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10950 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10960 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
10970 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
10980 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
10990 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
109a0 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
109b0 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
109c0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
109d0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
109e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
109f0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
10a00 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
10a10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
10a20 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10a40 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
10a50 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
10a60 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
10a70 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
10a80 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
10a90 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
10aa0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
10ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10ac0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
10ad0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
10ae0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
10af0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
10b00 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
10b10 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
10b20 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
10b30 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
10b40 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
10b50 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
10b60 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
10b70 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
10b80 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
10b90 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
10ba0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
10bb0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
10bc0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
10bd0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
10be0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
10bf0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
10c00 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
10c10 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
10c20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10c30 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
10c40 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
10c50 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
10c60 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
10c70 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
10c80 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
10c90 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
10ca0 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
10cb0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
10cc0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
10cd0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
10ce0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
10cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
10d00 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
10d10 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
10d20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
10d30 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
10d40 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
10d50 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
10d60 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
10d70 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
10d80 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10d90 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
10da0 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
10db0 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
10dc0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
10dd0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
10de0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
10df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
10e00 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
10e10 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
10e20 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
10e30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
10e50 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
10e60 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
10e70 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
10e80 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
10e90 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
10ea0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
10eb0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
10ec0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
10ed0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
10ee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
10ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10f00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
10f10 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
10f20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10f30 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
10f40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
10f50 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
10f60 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
10f70 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
10f80 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
10f90 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
10fa0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
10fb0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
10fc0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
10fd0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
10fe0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
10ff0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11000 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11010 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11020 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11030 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11040 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11050 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11060 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11070 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11080 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11090 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
110a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
110b0 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
110c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
110d0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
110e0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
110f0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11100 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11110 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11120 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11130 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11140 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11150 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11160 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
11170 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
11180 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11190 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
111a0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
111b0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
111c0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
111d0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
111e0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
111f0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11200 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11210 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11220 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11230 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11240 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11250 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11260 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
11270 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
11280 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11290 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
112a0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
112b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
112c0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
112d0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
112e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
112f0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11300 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11310 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11320 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11330 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11340 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11350 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11360 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11370 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11380 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11390 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
113a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
113b0 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
113c0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
113d0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
113e0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
113f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11400 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11410 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11420 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
11430 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
11440 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
11450 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
11460 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11470 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11490 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
114a0 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
114b0 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
114c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
114d0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
114e0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
114f0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11500 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11510 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11520 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11530 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11540 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11550 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11560 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11570 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11580 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11590 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
115a0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
115b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
115c0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
115d0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
115e0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
115f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11600 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11610 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11620 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11630 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11640 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11650 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11660 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11670 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11680 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11690 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
116a0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
116b0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
116c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
116d0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
116e0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
116f0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11700 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11710 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11720 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11730 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11740 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11750 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11760 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11770 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11780 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11790 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
117a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
117b0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
117c0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
117d0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
117e0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
117f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11800 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11810 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11820 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11830 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11840 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11850 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11860 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11870 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11880 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11890 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
118a0 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
118b0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
118c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
118d0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
118e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
118f0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11900 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11910 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11920 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11930 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11940 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11950 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11960 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11970 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11980 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11990 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
119a0 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
119b0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
119c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
119d0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
119e0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
119f0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11a00 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11a10 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11a30 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11a40 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11a50 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
11a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11a70 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11a80 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11a90 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11aa0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11ab0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11ac0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
11ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
11ae0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11af0 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
11b00 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
11b10 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
11b20 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
11b30 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
11b40 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
11b50 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
11b60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11b70 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
11b80 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
11b90 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
11ba0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
11bb0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
11bc0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
11bd0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
11be0 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
11bf0 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
11c00 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
11c10 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
11c20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11c30 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
11c40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11c50 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
11c60 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11c70 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
11c80 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
11c90 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
11ca0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
11cb0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
11cc0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11cd0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
11ce0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
11cf0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
11d00 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
11d10 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
11d20 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
11d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
11d40 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
11d50 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
11d60 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
11d70 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
11d80 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
11d90 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
11da0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
11db0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
11dc0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
11dd0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
11de0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
11df0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
11e00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11e10 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11e20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11e30 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
11e40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11e50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
11e60 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
11e70 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
11e80 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
11e90 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
11ea0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
11eb0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
11ec0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
11ed0 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
11ee0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
11ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11f00 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
11f10 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
11f20 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
11f30 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
11f40 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
11f50 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
11f60 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
11f70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
11f80 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11f90 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
11fa0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
11fb0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
11fc0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
11fd0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11fe0 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
11ff0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12000 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12010 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12020 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12030 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12040 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12050 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12060 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
12070 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
12080 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
12090 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
120a0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
120b0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
120c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
120d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
120e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
120f0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12100 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12110 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12120 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12130 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12140 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
12150 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12160 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
12170 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
12180 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
12190 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
121a0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
121b0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
121c0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
121d0 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
121e0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
121f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12200 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
12210 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
12220 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
12230 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
12240 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
12250 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
12260 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
12270 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12280 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12290 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
122a0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
122b0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
122c0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
122d0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
122e0 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
122f0 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
12300 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
12310 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
12320 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
12330 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
12340 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
12350 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
12360 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12370 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
12380 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12390 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
123a0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
123b0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
123c0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
123d0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
123e0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
123f0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
12400 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12410 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
12420 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
12430 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
12440 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
12450 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
12460 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
12470 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
12480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
12490 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
124a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
124b0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
124c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
124d0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
124e0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
124f0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
12500 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
12510 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
12520 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
12530 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
12540 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
12550 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
12560 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
12570 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
12580 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
12590 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
125a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
125b0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
125c0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
125d0 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
125e0 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
125f0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12600 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
12610 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
12620 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
12630 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
12640 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
12650 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
12660 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
12670 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
12680 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
12690 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
126a0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
126b0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
126c0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
126d0 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
126e0 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
126f0 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
12700 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
12710 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
12720 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
12730 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
12740 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
12750 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
12760 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
12770 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
12780 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
12790 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
127a0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
127b0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
127c0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
127d0 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
127e0 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
127f0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12800 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12810 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
12820 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
12830 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
12840 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
12850 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
12860 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
12870 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
12880 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
12890 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
128a0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
128b0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
128c0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
128d0 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
128e0 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
128f0 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
12900 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
12910 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
12920 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
12930 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
12940 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
12950 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12960 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
12970 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
12980 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12990 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
129a0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
129b0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
129c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
129d0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
129e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
129f0 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
12a00 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12a10 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12a20 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12a30 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
12a40 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
12a50 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
12a60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12a70 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
12a80 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
12a90 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
12aa0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
12ab0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
12ac0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
12ad0 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
12ae0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
12af0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
12b00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
12b10 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
12b20 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
12b30 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
12b40 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
12b50 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
12b60 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
12b70 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
12b80 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
12b90 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
12ba0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
12bb0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
12bc0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
12bd0 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
12be0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
12bf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
12c00 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
12c10 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
12c20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12c30 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
12c40 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
12c50 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
12c60 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
12c70 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
12c80 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
12c90 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
12ca0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
12cb0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
12cc0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
12cd0 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
12ce0 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
12cf0 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
12d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
12d10 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
12d20 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
12d30 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
12d40 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
12d50 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
12d60 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12d70 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
12d80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12d90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
12da0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
12db0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
12dc0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
12dd0 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
12de0 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
12df0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
12e00 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
12e10 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
12e20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12e30 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
12e40 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12e50 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
12e60 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12e70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12e80 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12e90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12ea0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
12eb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
12ec0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
12ed0 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
12ee0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
12ef0 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
12f00 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
12f10 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12f20 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
12f30 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
12f40 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12f50 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
12f60 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
12f70 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
12f80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12f90 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12fa0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
12fb0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
12fc0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12fd0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
12fe0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12ff0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13000 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13010 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13020 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13030 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13040 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13050 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13060 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13070 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
13080 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
13090 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
130a0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
130b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
130c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
130d0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
130e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
130f0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13100 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13110 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
13120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13130 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13140 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13150 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13160 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13170 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13180 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
13190 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
131a0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
131b0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
131c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
131d0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
131e0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
131f0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13200 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
13210 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
13220 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
13230 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
13240 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
13250 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
13260 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
13270 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
13280 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
13290 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
132a0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
132b0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
132c0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
132d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
132e0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
132f0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13300 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13310 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13320 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13330 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13340 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13350 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13360 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
13370 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
13380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13390 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
133a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
133b0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
133c0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
133d0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
133e0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
133f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13400 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
13410 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13420 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
13430 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
13440 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13450 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13460 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
13470 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
13480 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
13490 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
134a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
134b0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
134c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
134d0 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
134e0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
134f0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
13500 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
13510 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
13520 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13530 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
13540 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
13550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13560 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
13570 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
13580 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
13590 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
135a0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
135b0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
135c0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
135d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
135e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
135f0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
13600 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
13610 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
13620 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
13630 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13650 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13660 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13670 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13680 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13690 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
136a0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
136b0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
136c0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
136d0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
136e0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
136f0 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
13700 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
13710 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13730 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13740 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
13750 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
13760 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
13770 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
13780 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
13790 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
137a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
137b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137c0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
137d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
137e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
137f0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13800 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13810 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
13820 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13830 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13840 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
13850 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
13860 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13870 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
13880 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
13890 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
138a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
138b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
138c0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
138d0 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
138e0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
138f0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
13900 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
13910 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
13920 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
13930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13940 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
13950 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
13960 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
13970 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
13980 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
13990 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
139a0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
139b0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
139c0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
139d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
139e0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
139f0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
13a00 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
13a10 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
13a20 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
13a30 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13a40 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
13a50 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
13a60 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
13a70 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
13a80 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
13a90 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
13aa0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
13ab0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
13ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13ad0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
13ae0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
13af0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
13b00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13b10 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13b20 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
13b30 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
13b40 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
13b50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13b60 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
13b70 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
13b80 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
13b90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13ba0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
13bb0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
13bc0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
13bd0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
13be0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
13bf0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
13c00 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
13c10 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
13c20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
13c30 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
13c40 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
13c50 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
13c60 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
13c70 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
13c80 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
13c90 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
13ca0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
13cb0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
13cc0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
13cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13ce0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
13cf0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
13d00 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
13d10 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
13d20 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
13d30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13d40 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
13d50 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
13d60 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
13d70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13d80 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
13d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
13da0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20  I.** <dd>^(This 
13db0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13dc0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
13dd0 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e  f type int. If n
13de0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a  on-zero, then.**
13df0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
13e00 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
13e10 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
13e20 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ter is zero, the
13e30 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a  n URI handling.*
13e40 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  * is globally di
13e50 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
13e60 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
13e70 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
13e80 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
13e90 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
13ea0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
13eb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
13ec0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
13ed0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
13ee0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
13ef0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
13f00 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
13f10 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
13f20 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
13f30 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
13f40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
13f50 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
13f60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
13f70 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
13f80 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
13f90 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
13fa0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
13fb0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
13fc0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
13fd0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
13fe0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
13ff0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
14000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14010 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
14020 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
14030 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14040 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
14050 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
14060 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
14070 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
14080 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14090 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
140a0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
140b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
140c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
140d0 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
140f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
14100 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
14110 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14120 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
14130 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
14140 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
14150 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
14160 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
14170 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
14180 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
14190 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
141a0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
141b0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
141c0 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  r.  ^The default
141d0 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
141e0 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
141f0 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
14200 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14210 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
14220 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
14230 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
14240 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14250 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
14260 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
14270 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
14280 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14290 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
142a0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
142b0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
142c0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
142d0 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
142e0 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
142f0 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
14300 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
14310 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
14320 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
14330 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
14340 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14350 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
14360 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
14370 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
14380 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
14390 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
143a0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
143b0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
143c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
143d0 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
143e0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
143f0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14400 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
14410 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
14420 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
14430 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
14440 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
14450 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
14460 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
14470 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
14480 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
14490 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
144a0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
144b0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
144c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
144d0 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
144e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
144f0 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
14500 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
14510 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
14520 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
14530 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
14540 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
14550 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
14560 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
14570 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
14580 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
14590 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
145a0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
145b0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
145c0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
145d0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
145e0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
145f0 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
14600 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
14610 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
14620 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
14630 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
14640 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
14650 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
14660 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
14670 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
14680 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
14690 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
146a0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
146b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
146c0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
146d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
146e0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
146f0 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
14700 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
14710 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
14720 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
14730 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
14740 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
14750 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
14760 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
14770 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
14780 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
14790 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
147a0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
147b0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
147c0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
147d0 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
147e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
147f0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
14800 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
14810 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14820 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
14830 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
14840 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
14850 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
14860 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
14870 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
14880 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
14890 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
148a0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
148b0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
148c0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
148d0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
148e0 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
148f0 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
14900 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14910 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
14920 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14930 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
14940 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
14950 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
14960 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
14970 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
14980 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
14990 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
149a0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
149b0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
149c0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
149d0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
149e0 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
149f0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
14a00 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
14a10 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
14a20 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
14a30 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
14a40 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
14a50 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
14a60 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
14a70 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
14a80 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
14a90 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
14aa0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
14ab0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
14ac0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
14ad0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
14ae0 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63  e.** cannot be c
14af0 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69  hanged at run-ti
14b00 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65  me.  Nor may the
14b10 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
14b20 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78   mmap size.** ex
14b30 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65  ceed the compile
14b40 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
14b50 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
14b60 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
14b70 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
14b80 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14b90 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
14ba0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
14bb0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
14bc0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
14bd0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
14be0 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
14bf0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
14c00 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ult..** </dl>.*/
14c10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14c20 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
14c30 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
14c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14c50 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
14c60 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
14c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14c80 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14c90 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
14ca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14cb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14cc0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
14cd0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14ce0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
14cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14d00 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
14d10 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14d20 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14d40 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
14d50 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
14d60 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14d70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d80 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
14d90 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
14da0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14db0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14dc0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
14dd0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
14de0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
14df0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14e00 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14e10 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
14e20 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
14e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14e40 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
14e50 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14e60 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14e70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14e80 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
14e90 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
14ea0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
14eb0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
14ec0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
14ed0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
14ee0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
14ef0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
14f00 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14f10 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
14f20 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14f40 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
14f50 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
14f60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14f70 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
14f80 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
14f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14fa0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
14fb0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
14fc0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
14fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14fe0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
14ff0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
15000 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15010 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
15020 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
15030 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
15040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15050 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
15060 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
15070 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
15080 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15090 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
150a0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
150b0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
150c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
150d0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
150e0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
150f0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15100 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15110 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
15120 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
15130 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
15140 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
15150 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
15160 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
15170 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
15180 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
15190 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
151a0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
151b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
151c0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
151d0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
151e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
151f0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
15200 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
15210 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
15220 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
15230 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
15240 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
15250 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
15260 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
15270 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15280 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
15290 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
152a0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
152b0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
152c0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
152d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
152e0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
152f0 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
15300 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
15310 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
15320 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
15330 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
15340 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
15350 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
15360 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
15370 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
15380 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
15390 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
153a0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
153b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
153c0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
153d0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
153e0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
153f0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15400 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
15410 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
15420 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
15430 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
15440 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
15450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15460 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15470 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15480 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15490 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
154a0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
154b0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
154c0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
154d0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
154e0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
154f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15500 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
15510 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15520 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
15530 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
15540 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
15550 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
15560 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
15570 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
15580 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
15590 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
155a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
155b0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
155c0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
155d0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
155e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
155f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15600 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
15610 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
15620 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15630 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
15640 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
15650 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
15660 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
15670 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
15680 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
15690 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
156a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
156b0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
156c0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
156d0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
156e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
156f0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15700 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
15710 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
15720 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
15730 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
15740 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
15750 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
15760 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
15770 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15780 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
15790 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
157a0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
157b0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
157c0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
157d0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
157e0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
157f0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15800 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
15810 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
15820 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
15830 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
15840 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15850 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
15860 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
15870 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
15880 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
15890 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
158a0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
158b0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
158c0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
158d0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
158e0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
158f0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15900 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
15910 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15920 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15930 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
15940 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15950 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
15960 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
15970 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
15980 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
15990 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
159a0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
159b0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
159c0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
159d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
159e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
159f0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15a00 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
15a10 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
15a20 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
15a30 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
15a40 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
15a50 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
15a60 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
15a70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15a80 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15a90 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
15aa0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
15ab0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
15ac0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
15ad0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
15ae0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
15af0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15b00 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15b10 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15b20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15b30 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15b40 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
15b50 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
15b60 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
15b70 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
15b80 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
15b90 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
15ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15bb0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
15bc0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
15bd0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
15be0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15bf0 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
15c00 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
15c10 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
15c20 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
15c30 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
15c40 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
15c50 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
15c60 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
15c70 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
15c80 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
15c90 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
15ca0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
15cb0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
15cc0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
15cd0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15ce0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
15cf0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
15d00 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
15d10 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
15d20 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
15d30 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
15d40 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
15d50 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
15d60 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
15d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
15d80 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
15d90 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
15da0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
15db0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
15dc0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
15dd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
15de0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15df0 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
15e00 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
15e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15e20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15e30 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
15e40 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
15e50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15e60 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
15e70 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
15e80 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
15e90 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
15ea0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
15eb0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
15ec0 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
15ed0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
15ee0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
15ef0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
15f00 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
15f10 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
15f20 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
15f30 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
15f40 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
15f50 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
15f60 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
15f70 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
15f80 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
15f90 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
15fa0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
15fb0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
15fc0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
15fd0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
15fe0 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
15ff0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
16000 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
16010 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
16020 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
16030 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
16040 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
16050 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
16060 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
16070 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
16080 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
16090 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
160a0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
160b0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
160c0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
160d0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
160e0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
160f0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
16100 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
16110 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
16120 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
16130 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
16140 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
16150 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
16160 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
16170 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
16180 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
16190 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
161a0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
161b0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
161c0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
161d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
161e0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
161f0 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74   .** most recent
16200 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
16210 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
16220 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
16230 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
16240 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16250 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65  tion D..** ^Inse
16260 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
16270 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
16280 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64  are not recorded
16290 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
162a0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
162b0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
162c0 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  es.** have ever 
162d0 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20  occurred on the 
162e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
162f0 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20  ion D, .** then 
16300 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16310 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
16320 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
16330 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
16340 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
16350 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
16360 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
16370 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
16380 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
16390 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
163a0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
163b0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
163c0 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
163d0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
163e0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
163f0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
16400 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
16410 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
16420 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
16430 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
16440 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
16450 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
16460 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
16470 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
16480 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
16490 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
164a0 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
164b0 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
164c0 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
164d0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
164e0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
164f0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16500 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
16510 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
16520 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
16530 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
16540 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
16550 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
16560 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
16570 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
16580 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
16590 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
165a0 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
165b0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
165c0 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
165d0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
165e0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
165f0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
16600 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
16610 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
16620 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
16630 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
16640 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
16650 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
16660 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
16670 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
16680 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
16690 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
166a0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
166b0 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
166c0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
166d0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
166e0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
166f0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
16700 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
16710 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
16720 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
16730 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
16740 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
16750 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
16760 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
16770 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
16780 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
16790 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
167a0 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
167b0 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
167c0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
167d0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
167e0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
167f0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
16800 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
16810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16820 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
16830 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16840 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
16850 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
16860 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
16870 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
16880 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
16890 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
168a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
168b0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
168c0 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
168d0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
168e0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
168f0 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
16900 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
16910 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
16920 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
16930 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
16940 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16950 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
16960 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16970 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
16980 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
16990 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
169a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
169b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
169c0 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
169d0 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
169e0 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
169f0 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
16a00 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
16a10 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
16a20 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
16a30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16a40 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
16a50 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
16a60 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
16a70 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
16a80 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
16a90 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
16aa0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
16ab0 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
16ac0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
16ad0 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
16ae0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
16af0 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
16b00 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
16b10 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
16b20 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
16b30 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
16b40 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
16b50 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
16b60 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
16b70 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
16b80 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
16b90 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
16ba0 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
16bb0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
16bc0 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
16bd0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
16be0 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
16bf0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
16c00 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
16c10 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
16c20 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
16c30 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
16c40 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
16c50 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
16c60 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
16c70 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
16c80 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
16c90 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
16ca0 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
16cb0 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
16cc0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
16cd0 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
16ce0 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
16cf0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
16d00 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
16d10 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
16d20 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
16d30 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
16d40 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
16d50 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
16d60 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
16d70 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
16d80 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
16d90 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
16da0 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
16db0 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
16dc0 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
16dd0 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
16de0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
16df0 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
16e00 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
16e10 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
16e20 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
16e30 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
16e40 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
16e50 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
16e60 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
16e70 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
16e80 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
16e90 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
16ea0 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
16eb0 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
16ec0 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
16ed0 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
16ee0 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
16ef0 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
16f00 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
16f10 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
16f20 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
16f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
16f40 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
16f50 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
16f60 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
16f70 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
16f80 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
16f90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
16fa0 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
16fb0 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
16fc0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
16fd0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16fe0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
16ff0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
17000 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
17020 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
17030 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
17040 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
17050 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
17060 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
17070 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17080 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
17090 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
170a0 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
170b0 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
170c0 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
170d0 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
170e0 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
170f0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
17100 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
17110 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
17120 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
17130 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
17140 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
17150 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
17160 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
17170 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
17180 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
17190 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
171a0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
171b0 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
171c0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
171d0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
171e0 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
171f0 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
17200 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
17210 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
17220 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
17230 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17240 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
17250 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
17260 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
17270 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
17280 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17290 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
172a0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
172b0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
172c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
172d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
172e0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
172f0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
17300 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
17310 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
17320 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17330 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
17340 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
17350 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61   int sqlite3_cha
17360 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
17370 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17380 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
17390 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
173a0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
173b0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
173c0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
173d0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
173e0 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
173f0 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
17400 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
17410 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
17420 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
17430 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
17440 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
17450 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
17460 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
17470 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
17480 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
17490 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
174a0 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
174b0 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
174c0 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
174d0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
174e0 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
174f0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
17500 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
17510 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
17520 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
17530 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
17540 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
17550 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
17560 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
17570 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
17580 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
17590 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
175a0 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
175b0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
175c0 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
175d0 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
175e0 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
175f0 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
17600 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
17610 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
17620 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
17630 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17640 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
17650 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
17660 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
17670 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
17680 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
17690 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
176a0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
176b0 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
176c0 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
176d0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
176e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
176f0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
17700 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
17710 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
17720 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
17730 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
17740 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
17750 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
17760 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17770 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17780 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
17790 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
177a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
177b0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
177c0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
177d0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
177e0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
177f0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
17800 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17810 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
17820 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
17830 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74   int sqlite3_tot
17840 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
17850 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17860 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
17870 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
17880 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
17890 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
178a0 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
178b0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
178c0 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
178d0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
178e0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
178f0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
17900 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
17910 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
17920 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
17930 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
17940 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
17950 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
17960 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
17970 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
17980 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
17990 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
179a0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
179b0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
179c0 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
179d0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
179e0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
179f0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
17a00 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
17a10 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
17a20 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
17a30 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
17a40 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
17a50 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
17a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
17a70 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
17a80 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
17a90 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
17aa0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
17ab0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
17ac0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
17ad0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
17ae0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
17af0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
17b00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
17b10 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
17b20 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
17b30 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
17b40 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
17b50 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
17b60 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
17b70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
17b80 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
17b90 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
17ba0 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
17bb0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
17bc0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
17bd0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
17be0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
17bf0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
17c00 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
17c10 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
17c20 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
17c30 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
17c40 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
17c50 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
17c60 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
17c70 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
17c80 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17c90 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
17ca0 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
17cb0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
17cc0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
17cd0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
17ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
17cf0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
17d00 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
17d10 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
17d20 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
17d30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17d40 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
17d50 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
17d60 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
17d70 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
17d80 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
17d90 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
17da0 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
17db0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
17dc0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
17dd0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
17de0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
17df0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
17e00 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
17e10 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
17e20 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
17e30 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
17e40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
17e50 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
17e60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
17e70 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
17e80 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
17e90 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
17ea0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
17eb0 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
17ec0 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
17ed0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
17ee0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
17ef0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
17f00 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17f10 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
17f20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
17f30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17f40 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
17f50 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
17f60 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
17f70 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
17f80 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
17f90 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  y happen..*/.SQL
17fa0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
17fb0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
17fc0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17fd0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
17fe0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
17ff0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
18000 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
18010 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
18020 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
18030 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
18040 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
18050 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
18060 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
18070 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
18080 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
18090 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
180a0 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
180b0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
180c0 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
180d0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
180e0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
180f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18100 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
18110 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
18120 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
18130 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
18140 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
18150 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
18160 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
18170 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
18180 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
18190 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
181a0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
181b0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
181c0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
181d0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
181e0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
181f0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
18200 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
18210 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
18220 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
18230 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
18240 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
18250 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
18260 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
18270 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
18280 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
18290 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
182a0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
182b0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
182c0 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
182d0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
182e0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
182f0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
18300 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
18310 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18320 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
18330 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
18340 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
18350 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
18360 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
18370 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
18380 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
18390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
183a0 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
183b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
183c0 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
183d0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
183e0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
183f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
18400 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
18410 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
18420 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
18430 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
18440 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
18450 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18460 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
18470 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
18480 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
18490 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
184a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
184b0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
184c0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
184d0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
184e0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
184f0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
18500 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
18510 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
18520 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
18530 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
18540 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
18550 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
18560 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
18570 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
18580 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
18590 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
185a0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
185b0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
185c0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
185d0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
185e0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
185f0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
18600 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
18610 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
18620 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
18630 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
18640 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   *sql);.SQLITE_A
18650 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
18660 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
18670 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
18680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
18690 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
186a0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
186b0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
186c0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
186d0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
186e0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
186f0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
18700 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
18710 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
18720 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
18730 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
18740 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
18750 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
18760 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
18770 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
18780 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
18790 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
187a0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
187b0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
187c0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
187d0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
187e0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
187f0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
18800 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
18810 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
18820 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
18830 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
18840 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
18850 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
18860 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
18870 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
18880 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
18890 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
188a0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
188b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
188c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
188d0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
188e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
188f0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18900 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
18910 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
18920 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
18930 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
18940 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
18950 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
18960 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
18970 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
18980 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
18990 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
189a0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
189b0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
189c0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
189d0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
189e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
189f0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
18a00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
18a10 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
18a20 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
18a30 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
18a40 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
18a50 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
18a60 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
18a70 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
18a80 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
18a90 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
18aa0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
18ab0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
18ac0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
18ad0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
18ae0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
18af0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
18b00 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
18b10 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
18b20 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
18b30 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
18b40 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
18b50 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
18b60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
18b70 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
18b80 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
18b90 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
18ba0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
18bb0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
18bc0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
18bd0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
18be0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
18bf0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
18c00 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
18c10 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
18c20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
18c30 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
18c40 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
18c50 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
18c60 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
18c70 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
18c80 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
18c90 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
18ca0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
18cb0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
18cc0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
18cd0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
18ce0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
18cf0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
18d00 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
18d10 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
18d20 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
18d30 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
18d40 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18d50 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
18d60 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
18d70 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
18d80 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
18d90 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
18da0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
18db0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
18dc0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
18dd0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
18de0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
18df0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
18e00 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
18e10 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
18e20 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
18e30 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
18e40 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18e50 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
18e60 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
18e70 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
18e80 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
18e90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
18ea0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
18eb0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
18ec0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
18ed0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
18ee0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
18ef0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
18f00 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
18f10 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
18f20 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
18f30 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
18f40 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
18f50 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
18f60 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
18f70 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
18f80 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
18f90 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
18fa0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
18fb0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
18fc0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
18fd0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
18fe0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
18ff0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
19000 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
19010 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
19020 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
19030 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
19040 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
19050 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
19060 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
19070 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
19080 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
19090 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
190a0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
190b0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
190c0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
190d0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
190e0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
190f0 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
19100 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
19110 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
19120 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
19130 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
19140 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
19150 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
19160 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
19170 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
19180 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
19190 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
191a0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
191b0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
191c0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
191d0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
191e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
191f0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
19200 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19210 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
19220 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
19230 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
19240 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
19250 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
19260 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
19270 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19280 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
19290 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
192a0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
192b0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
192c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
192d0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
192e0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
192f0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
19300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19310 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19320 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
19330 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
19340 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
19350 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
19360 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
19370 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
19380 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
19390 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
193a0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
193b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
193c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
193d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
193e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
193f0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19400 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
19410 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
19420 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
19430 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
19440 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
19450 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
19460 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
19470 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
19480 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
19490 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
194a0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
194b0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
194c0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
194d0 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
194e0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
194f0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
19500 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
19510 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
19520 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
19530 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
19540 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
19550 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
19560 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
19570 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
19580 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
19590 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
195a0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
195b0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
195c0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
195d0 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
195e0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
195f0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
19600 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
19610 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
19620 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
19630 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
19640 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
19650 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
19660 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
19670 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
19680 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
19690 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
196a0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
196b0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
196c0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
196d0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
196e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
196f0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
19700 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
19710 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
19720 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
19730 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
19740 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  d.)^.*/.SQLITE_A
19750 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
19760 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
19770 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
19780 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19790 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
197a0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
197b0 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
197c0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
197d0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
197e0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
197f0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
19800 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
19810 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
19820 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
19830 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
19840 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
19850 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
19860 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
19870 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
19880 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
19890 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
198a0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
198b0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
198c0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
198d0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
198e0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
198f0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
19900 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
19910 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
19920 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
19930 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
19940 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
19950 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
19960 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
19970 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
19980 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
19990 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
199a0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
199b0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
199c0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
199d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
199e0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
199f0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
19a00 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
19a10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
19a20 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
19a30 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
19a40 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
19a50 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
19a60 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
19a70 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
19a80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
19a90 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
19aa0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
19ab0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
19ac0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
19ad0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
19ae0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
19af0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
19b00 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
19b10 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
19b20 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
19b30 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
19b40 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
19b50 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
19b60 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
19b70 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
19b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
19b90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
19ba0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
19bb0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
19bc0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
19bd0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
19be0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
19bf0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
19c00 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
19c10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
19c20 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
19c30 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
19c40 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
19c50 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
19c60 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
19c70 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
19c80 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
19c90 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
19ca0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
19cb0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
19cc0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19cd0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
19ce0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
19cf0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
19d00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19d10 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
19d20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
19d30 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
19d40 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
19d50 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
19d60 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
19d70 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
19d80 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
19d90 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
19da0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
19db0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
19dc0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
19dd0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
19de0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
19df0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
19e00 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
19e10 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
19e20 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
19e30 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
19e40 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
19e50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19e60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19e70 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
19e80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
19e90 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
19ea0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
19eb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
19ec0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
19ed0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19ee0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
19ef0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19f00 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
19f10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19f20 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
19f30 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19f40 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
19f50 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
19f60 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
19f70 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
19f80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
19f90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
19fa0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
19fb0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
19fc0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
19fd0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
19fe0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
19ff0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1a000 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1a010 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1a020 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1a030 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1a040 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1a050 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1a060 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1a070 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1a080 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1a090 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1a0a0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1a0b0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1a0c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1a0d0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1a0e0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a0f0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1a100 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1a110 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1a120 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1a130 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1a140 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1a150 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1a160 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a170 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1a180 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1a190 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1a1a0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1a1b0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1a1c0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1a1d0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1a1e0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1a1f0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1a200 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1a210 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1a220 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1a230 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a240 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1a250 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1a260 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1a270 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1a280 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1a290 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1a2a0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1a2b0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1a2c0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1a2d0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1a2e0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1a2f0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1a300 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1a310 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1a320 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1a330 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1a340 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1a350 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1a360 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1a370 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1a380 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1a390 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1a3a0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1a3b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1a3c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1a3d0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1a3e0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1a3f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1a400 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a410 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1a420 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1a430 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1a440 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1a450 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1a460 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1a470 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1a480 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1a490 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1a4a0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1a4b0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1a4c0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1a4d0 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1a4e0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1a4f0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1a500 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1a510 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1a520 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1a530 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1a540 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1a550 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1a560 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1a570 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1a580 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1a590 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1a5a0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1a5b0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1a5c0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1a5d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1a5e0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1a5f0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1a600 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1a610 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1a620 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1a630 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
1a640 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1a650 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1a660 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1a670 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1a680 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1a690 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1a6a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1a6b0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1a6c0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1a6d0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1a6e0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1a6f0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1a700 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a710 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1a720 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1a730 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1a740 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a750 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1a760 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1a770 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1a780 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1a790 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1a7a0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1a7b0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1a7c0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1a7d0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1a7e0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1a7f0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1a800 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1a810 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1a820 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1a830 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a840 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1a850 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1a860 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1a870 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1a880 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1a890 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1a8a0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1a8b0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1a8c0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1a8d0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1a8e0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1a8f0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1a900 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1a910 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1a920 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1a930 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1a940 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1a950 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1a960 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1a970 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1a980 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1a990 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1a9a0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1a9b0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1a9c0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1a9d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1a9e0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1a9f0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1aa00 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1aa10 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1aa20 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1aa30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1aa40 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1aa50 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1aa60 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1aa70 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1aa80 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1aa90 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1aaa0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1aab0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1aac0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1aad0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1aae0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1aaf0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1ab00 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1ab10 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1ab20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1ab30 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1ab40 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1ab50 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1ab60 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1ab70 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1ab80 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1ab90 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1aba0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1abb0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1abc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1abd0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1abe0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1abf0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1ac00 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1ac10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1ac20 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1ac30 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1ac40 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1ac50 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1ac60 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1ac70 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1ac80 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1ac90 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1aca0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1acb0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1acc0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1acd0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1ace0 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
1acf0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1ad00 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1ad10 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1ad20 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1ad30 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1ad40 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1ad50 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1ad60 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1ad70 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1ad80 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1ad90 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1ada0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1adb0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1adc0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1add0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1ade0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1adf0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1ae00 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1ae10 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1ae20 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1ae30 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1ae40 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1ae50 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1ae60 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1ae70 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1ae80 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1ae90 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1aea0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1aeb0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1aec0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1aed0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1aee0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1aef0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1af00 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1af10 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1af20 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1af30 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1af40 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1af50 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1af60 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1af70 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1af80 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1af90 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1afa0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1afb0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1afc0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1afd0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1afe0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1aff0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1b000 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1b010 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1b020 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1b030 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1b040 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b050 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b060 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1b070 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1b080 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1b090 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1b0a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b0b0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1b0c0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1b0d0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1b0e0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1b0f0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1b100 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1b110 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1b120 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b130 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1b140 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1b150 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1b160 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b170 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b180 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1b190 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1b1a0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1b1b0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1b1c0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1b1d0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1b1e0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1b1f0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1b200 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1b210 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1b220 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b230 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1b240 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1b250 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1b260 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1b270 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1b280 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1b290 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1b2a0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1b2b0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1b2c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1b2d0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1b2e0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1b2f0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1b300 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1b310 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1b320 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1b330 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b340 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1b350 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1b360 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1b370 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1b380 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1b390 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1b3a0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1b3b0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1b3c0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1b3d0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b3e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1b3f0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1b400 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1b410 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1b420 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1b430 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1b440 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1b450 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1b460 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1b470 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b480 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1b490 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1b4a0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1b4b0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1b4c0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1b4d0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1b4e0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1b4f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b500 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1b510 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1b520 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
1b530 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1b540 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b550 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,...);.SQLITE_AP
1b560 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1b570 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1b580 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1b590 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1b5a0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1b5b0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1b5c0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
1b5d0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1b5e0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1b5f0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1b600 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1b610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b620 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1b630 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1b640 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1b650 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1b660 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1b670 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1b680 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1b690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b6a0 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1b6b0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1b6c0 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1b6d0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1b6e0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1b6f0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1b700 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1b710 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1b720 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1b730 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1b740 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1b750 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1b760 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1b770 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1b780 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1b790 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1b7a0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1b7b0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1b7c0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1b7d0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1b7e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1b7f0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1b800 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1b810 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1b820 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1b830 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1b840 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1b850 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1b860 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1b870 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1b880 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1b890 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1b8a0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1b8b0 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1b8c0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1b8d0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1b8e0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1b8f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1b900 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1b910 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1b920 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1b930 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1b940 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1b950 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1b960 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1b970 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1b980 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1b990 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1b9a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1b9b0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1b9c0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1b9d0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1b9e0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1b9f0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1ba00 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1ba10 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1ba20 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1ba30 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1ba40 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1ba50 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1ba60 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1ba70 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1ba80 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1ba90 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1baa0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1bab0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1bac0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1bad0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1bae0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1baf0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1bb00 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1bb10 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1bb20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1bb30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bb40 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1bb50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bb60 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1bb70 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1bb80 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1bb90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1bba0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1bbb0 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1bbc0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1bbd0 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1bbe0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1bbf0 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1bc00 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1bc10 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1bc20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1bc30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1bc40 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1bc50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1bc60 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1bc70 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1bc80 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1bc90 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1bca0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1bcb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1bcc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1bcd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1bce0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1bcf0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bd00 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1bd10 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1bd20 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1bd30 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1bd40 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1bd50 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1bd60 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1bd70 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1bd80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bd90 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1bda0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1bdb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1bdc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1bdd0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1bde0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1bdf0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1be00 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1be10 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1be20 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1be30 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1be40 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1be50 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1be60 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1be70 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1be80 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1be90 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1bea0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1beb0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1bec0 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1bed0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1bee0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1bef0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1bf00 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1bf10 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1bf20 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1bf30 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1bf40 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1bf50 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1bf60 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1bf70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1bf80 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1bf90 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1bfa0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1bfb0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1bfc0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1bfd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1bfe0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1bff0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1c000 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1c010 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1c020 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c030 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1c040 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1c050 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1c060 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1c070 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1c080 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1c090 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1c0a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c0b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1c0c0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1c0d0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1c0e0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1c0f0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1c100 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1c110 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1c120 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1c130 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1c140 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1c150 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1c160 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1c170 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1c180 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c190 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1c1a0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1c1b0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1c1c0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1c1d0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1c1e0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1c1f0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1c200 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1c210 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1c220 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1c230 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1c240 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1c250 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1c260 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1c270 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1c280 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1c290 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1c2a0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1c2b0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1c2c0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1c2d0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1c2e0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1c2f0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1c300 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1c310 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1c320 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1c330 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1c340 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1c350 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1c360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c370 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1c380 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1c390 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1c3a0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1c3b0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1c3c0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1c3d0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1c3e0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1c3f0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1c400 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1c410 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1c420 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c430 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1c440 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1c450 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1c460 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1c470 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1c480 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1c490 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  c(void*, int);.S
1c4a0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1c4b0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1c4c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c4d0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1c4e0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1c4f0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1c500 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1c510 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1c520 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1c530 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1c540 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1c550 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1c560 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1c570 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1c580 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1c590 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1c5a0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1c5b0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1c5c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1c5d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1c5e0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1c5f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1c600 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1c610 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1c620 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1c630 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1c640 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1c650 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1c660 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1c670 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1c680 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1c690 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1c6a0 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1c6b0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1c6c0 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1c6d0 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1c6e0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1c6f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c700 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1c710 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c720 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1c730 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1c740 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1c750 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1c760 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1c770 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c780 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1c790 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1c7a0 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1c7b0 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1c7c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1c7d0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1c7e0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1c7f0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1c800 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1c810 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1c820 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1c830 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1c840 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1c850 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1c860 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1c870 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c880 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1c890 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1c8a0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1c8b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c8c0 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1c8d0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1c8e0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1c8f0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1c900 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1c910 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1c920 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1c930 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1c940 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1c950 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1c960 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1c970 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1c980 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1c990 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1c9a0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1c9b0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1c9c0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1c9d0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1c9e0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1c9f0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1ca00 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1ca10 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1ca20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1ca30 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1ca40 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1ca50 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1ca60 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1ca70 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1ca80 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1ca90 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1caa0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1cab0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1cac0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1cad0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1cae0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1caf0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1cb00 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1cb10 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1cb20 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1cb30 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1cb40 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1cb50 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1cb60 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1cb70 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1cb80 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1cb90 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1cba0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1cbb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1cbc0 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1cbd0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1cbe0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1cbf0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1cc00 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1cc10 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1cc20 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1cc30 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1cc40 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1cc50 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1cc60 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1cc70 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1cc80 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1cc90 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1cca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1ccb0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1ccc0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
1ccd0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1cce0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1ccf0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1cd00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cd10 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1cd20 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1cd30 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1cd40 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1cd50 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1cd60 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1cd70 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1cd80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cd90 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1cda0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1cdb0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1cdc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cdd0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1cde0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1cdf0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1ce00 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1ce10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1ce20 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1ce30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ce40 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1ce50 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1ce60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ce70 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1ce80 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1ce90 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1cea0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1ceb0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1cec0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1ced0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1cee0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1cef0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cf00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1cf10 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1cf20 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1cf30 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1cf40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1cf50 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1cf60 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1cf70 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1cf80 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1cf90 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1cfa0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1cfb0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1cfc0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1cfd0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1cfe0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1cff0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1d000 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1d010 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1d020 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1d030 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1d040 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1d050 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d060 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1d070 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1d080 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d090 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1d0a0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1d0b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1d0c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d0d0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1d0e0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1d0f0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1d100 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1d110 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1d120 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1d130 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1d140 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d150 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1d160 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1d170 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1d180 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1d190 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1d1a0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1d1b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d1c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1d1d0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1d1e0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1d1f0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1d200 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1d210 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1d220 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1d230 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1d240 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1d250 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1d260 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1d270 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1d280 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1d290 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1d2a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1d2b0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1d2c0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1d2d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1d2e0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1d2f0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1d300 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1d310 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1d320 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1d330 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1d340 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1d350 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1d360 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1d370 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1d380 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1d390 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1d3a0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1d3b0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1d3c0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1d3d0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1d3e0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1d3f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1d400 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1d410 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1d420 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1d430 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1d440 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1d450 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1d460 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1d470 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1d480 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1d490 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1d4a0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1d4b0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1d4c0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1d4d0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1d4e0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1d4f0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1d500 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1d510 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1d520 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1d530 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1d540 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1d550 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1d560 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1d570 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1d580 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1d590 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1d5a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1d5b0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1d5c0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1d5d0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1d5e0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1d5f0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1d600 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1d610 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1d620 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1d630 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1d640 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1d650 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1d660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1d670 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1d680 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1d690 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1d6a0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1d6b0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1d6c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1d6d0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1d6e0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1d6f0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1d700 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1d710 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1d720 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1d730 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1d740 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1d750 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1d760 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1d770 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1d780 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1d790 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1d7a0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1d7b0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1d7c0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1d7d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1d7e0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1d7f0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1d800 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1d810 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1d820 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d830 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1d840 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1d850 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1d860 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1d870 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1d880 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1d890 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1d8a0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1d8b0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1d8c0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1d8d0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1d8e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1d8f0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1d900 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1d910 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1d920 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1d930 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1d940 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1d950 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1d960 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1d970 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1d980 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1d990 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1d9a0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1d9b0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1d9c0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1d9d0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1d9e0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1d9f0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1da00 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1da10 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1da20 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1da30 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1da40 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1da50 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1da60 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1da70 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1da80 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1da90 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1daa0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1dab0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1dac0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1dad0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1dae0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1daf0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1db00 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1db10 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1db20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1db30 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1db40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1db50 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1db60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1db70 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1db80 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1db90 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1dba0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dbb0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1dbc0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1dbd0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1dbe0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1dbf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dc00 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1dc10 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1dc20 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1dc30 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1dc40 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1dc50 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1dc60 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1dc70 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1dc80 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1dc90 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1dca0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1dcb0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1dcc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1dcd0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1dce0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1dcf0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1dd00 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1dd10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1dd20 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1dd30 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1dd40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dd50 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1dd60 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1dd70 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1dd80 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1dd90 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1dda0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1ddb0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1ddc0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1ddd0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1dde0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1ddf0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1de00 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1de10 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1de20 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1de30 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1de40 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  change..*/.SQLIT
1de50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1de60 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1de70 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1de80 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1de90 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1dea0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1deb0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1dec0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1ded0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1dee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1def0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1df00 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1df10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1df20 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1df30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1df40 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1df50 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1df60 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1df70 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1df80 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1df90 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1dfa0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1dfb0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1dfc0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1dfd0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1dfe0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1dff0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1e000 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1e010 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1e020 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1e030 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1e040 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1e050 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1e060 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1e070 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1e080 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1e090 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1e0a0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1e0b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e0c0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1e0d0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1e0e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1e0f0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1e100 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1e110 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1e120 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1e130 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1e140 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1e150 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e160 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1e170 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e180 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e190 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1e1a0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1e1b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1e1c0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1e1d0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1e1e0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1e1f0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1e200 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1e210 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1e220 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e230 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1e240 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1e250 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1e260 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1e270 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1e280 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1e290 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1e2a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e2b0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1e2c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1e2d0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1e2e0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1e2f0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1e300 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1e310 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1e320 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1e330 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1e340 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1e350 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1e360 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1e370 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1e380 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1e390 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1e3a0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1e3b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1e3c0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1e3d0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1e3e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e3f0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1e400 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1e410 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1e420 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1e430 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1e440 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1e450 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e460 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1e470 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1e480 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1e490 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1e4a0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1e4b0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1e4c0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1e4d0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1e4e0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1e4f0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1e500 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1e510 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1e520 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e530 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1e540 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1e550 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1e560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e570 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1e580 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1e590 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e5a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e5b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e5c0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1e5d0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1e5e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e5f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e600 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e610 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1e620 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1e630 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e640 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e650 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e660 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1e670 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1e680 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e690 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e6a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e6b0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1e6c0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1e6d0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e6e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e6f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e700 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1e710 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e720 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e730 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e740 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e750 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1e760 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1e770 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1e780 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e790 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1e7a0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1e7b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1e7c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e7d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e7e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1e7f0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1e800 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e810 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e820 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e830 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1e840 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1e850 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e860 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e870 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e880 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1e890 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1e8a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e8b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e8c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e8d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1e8e0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1e8f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1e900 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e920 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1e930 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1e940 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e950 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e970 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1e980 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1e990 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1e9a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e9b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e9c0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1e9d0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1e9e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1e9f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ea00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ea10 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1ea20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1ea30 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1ea40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ea50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ea60 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1ea70 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1ea80 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1ea90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1eaa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1eab0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1eac0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1ead0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1eae0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1eaf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1eb00 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1eb10 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1eb20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1eb30 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1eb40 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1eb50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eb60 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1eb70 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1eb80 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1eb90 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1eba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1ebb0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1ebc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ebd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ebe0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1ebf0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1ec00 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1ec10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ec20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ec30 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1ec40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1ec50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ec60 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1ec70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ec80 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1ec90 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1eca0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1ecb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ecc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ecd0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1ece0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1ecf0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1ed00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ed10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ed20 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1ed30 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1ed40 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1ed50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ed60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ed70 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1ed80 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1ed90 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1eda0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1edb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1edc0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1edd0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1ede0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1edf0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ee00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ee10 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1ee20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1ee30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1ee40 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1ee50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ee60 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1ee70 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1ee80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1ee90 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1eea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eeb0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1eec0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1eed0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1eee0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1eef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1ef00 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1ef10 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1ef20 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1ef30 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1ef40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1ef50 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1ef60 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1ef70 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1ef80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1ef90 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1efa0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1efb0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1efc0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1efd0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1efe0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1eff0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1f000 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1f010 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1f020 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1f030 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1f040 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1f050 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1f060 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1f070 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1f080 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1f090 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1f0a0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1f0b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1f0c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f0d0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1f0e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1f0f0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1f100 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1f110 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1f120 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1f130 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1f140 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1f150 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1f160 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1f170 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1f180 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1f190 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1f1a0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1f1b0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1f1c0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1f1d0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1f1e0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1f1f0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1f200 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
1f210 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
1f220 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
1f230 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
1f240 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
1f250 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
1f260 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
1f270 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
1f280 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
1f290 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
1f2a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1f2b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1f2c0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1f2d0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1f2e0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1f2f0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1f300 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1f310 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1f320 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1f330 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1f340 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1f350 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1f360 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1f370 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1f380 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1f390 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1f3a0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1f3b0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1f3c0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1f3d0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1f3e0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1f3f0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1f400 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1f410 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1f420 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1f430 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1f440 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1f450 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1f460 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1f470 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1f480 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1f490 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1f4a0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1f4b0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1f4c0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1f4d0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1f4e0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1f4f0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1f500 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1f510 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1f520 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1f530 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
1f540 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1f550 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1f560 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1f570 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1f580 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1f590 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1f5a0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1f5b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1f5c0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1f5d0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1f5e0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f5f0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1f600 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1f610 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1f620 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1f630 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1f640 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1f650 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1f660 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1f670 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1f680 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1f690 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1f6a0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1f6b0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1f6c0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1f6d0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1f6e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1f6f0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1f700 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1f710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f720 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1f730 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1f740 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1f750 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1f760 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1f770 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1f780 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1f790 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1f7a0 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1f7b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1f7c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1f7d0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1f7e0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1f7f0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
1f800 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1f810 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1f820 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1f830 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1f840 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1f850 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1f860 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1f870 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
1f880 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
1f890 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
1f8a0 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
1f8b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
1f8c0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1f8d0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1f8e0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1f8f0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1f900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f910 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1f920 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1f930 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1f940 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1f950 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1f960 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1f970 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1f980 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1f990 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1f9a0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1f9b0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1f9c0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1f9d0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1f9e0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1f9f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fa00 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1fa10 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1fa20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1fa30 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1fa40 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1fa50 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1fa60 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1fa70 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1fa80 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1fa90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1faa0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1fab0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1fac0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1fad0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1fae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1faf0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1fb00 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1fb10 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1fb20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fb30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fb40 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1fb50 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1fb60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fb70 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1fb80 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1fb90 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1fba0 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
1fbb0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
1fbc0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1fbd0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1fbe0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1fbf0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1fc00 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1fc10 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1fc20 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1fc30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1fc40 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1fc50 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1fc60 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1fc70 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1fc80 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1fc90 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1fca0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1fcb0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1fcc0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1fcd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fce0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1fcf0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1fd00 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1fd10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1fd20 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1fd30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1fd40 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1fd50 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1fd60 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1fd70 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1fd80 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1fd90 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1fda0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1fdb0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1fdc0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1fdd0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1fde0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1fdf0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1fe00 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1fe10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1fe20 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1fe30 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1fe40 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1fe50 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1fe60 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1fe70 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1fe80 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1fe90 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1fea0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1feb0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1fec0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1fed0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1fee0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1fef0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1ff00 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1ff10 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1ff20 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1ff30 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1ff40 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1ff50 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1ff60 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1ff70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1ff80 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1ff90 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1ffa0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1ffb0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1ffc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1ffd0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1ffe0 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1fff0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
20000 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
20010 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
20020 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
20030 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
20040 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
20050 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
20060 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
20070 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
20080 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
20090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
200a0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
200b0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
200c0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
200d0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
200e0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
200f0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
20100 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20110 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
20120 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
20130 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
20140 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
20150 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
20160 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
20170 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
20180 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
20190 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
201a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
201b0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
201c0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
201d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
201e0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
201f0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
20200 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
20210 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
20220 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
20230 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
20240 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
20250 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
20260 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20270 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
20280 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20290 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
202a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
202b0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
202c0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
202d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
202e0 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
202f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20300 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
20310 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
20320 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
20330 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
20340 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
20350 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
20360 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
20370 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20380 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
20390 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
203a0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
203b0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
203c0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
203d0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
203e0 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
203f0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
20400 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
20410 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
20420 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
20430 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
20440 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
20450 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
20460 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
20470 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
20480 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20490 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
204a0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
204b0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
204c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
204d0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
204e0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
204f0 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
20500 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
20510 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
20520 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
20530 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
20540 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
20550 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
20560 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20570 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
20580 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
20590 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
205a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
205b0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
205c0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
205d0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
205e0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
205f0 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
20600 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
20610 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
20620 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
20630 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
20640 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
20650 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20660 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
20670 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
20680 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
20690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
206a0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
206b0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
206c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
206d0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
206e0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
206f0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
20700 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
20710 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
20720 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
20730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
20740 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
20750 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
20760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20770 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
20780 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
20790 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
207a0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
207b0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
207c0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
207d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
207e0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
207f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
20800 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
20810 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
20820 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20830 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
20840 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
20850 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
20860 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
20870 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
20880 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
20890 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
208a0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
208b0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
208c0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
208d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
208e0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
208f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20900 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
20910 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
20920 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
20930 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
20940 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
20950 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
20960 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
20970 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
20980 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
20990 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
209a0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
209b0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
209c0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
209d0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
209e0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
209f0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
20a00 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
20a10 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
20a20 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
20a30 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
20a40 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
20a50 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
20a60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
20a70 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
20a80 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
20a90 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
20aa0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
20ab0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
20ac0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
20ad0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
20ae0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
20af0 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
20b00 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
20b10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
20b20 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
20b30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
20b40 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
20b50 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
20b60 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
20b70 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
20b80 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
20b90 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
20ba0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
20bb0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
20bc0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
20bd0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
20be0 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
20bf0 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
20c00 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
20c10 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
20c20 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
20c30 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
20c40 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
20c50 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
20c60 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
20c70 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
20c80 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
20c90 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
20ca0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
20cb0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
20cc0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
20cd0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
20ce0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
20cf0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
20d00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
20d10 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
20d20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
20d30 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
20d40 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
20d50 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
20d60 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
20d70 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
20d80 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
20d90 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
20da0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
20db0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
20dc0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
20dd0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
20de0 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
20df0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
20e00 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
20e10 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
20e20 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
20e30 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
20e40 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
20e50 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
20e60 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
20e70 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
20e80 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
20e90 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
20ea0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
20eb0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
20ec0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
20ed0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
20ee0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
20ef0 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
20f00 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
20f10 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
20f20 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
20f30 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
20f40 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
20f50 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
20f60 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
20f70 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
20f80 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
20f90 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
20fa0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
20fb0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
20fc0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
20fd0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
20fe0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
20ff0 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
21000 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
21010 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
21020 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
21030 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
21040 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
21050 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
21060 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
21070 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
21080 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
21090 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
210a0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
210b0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
210c0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
210d0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
210e0 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
210f0 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
21100 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
21110 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
21120 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
21130 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
21140 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
21150 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
21160 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
21170 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
21180 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
21190 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
211a0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
211b0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
211c0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
211d0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
211e0 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
211f0 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
21200 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
21210 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
21220 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
21230 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
21240 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
21250 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
21260 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
21270 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
21280 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
21290 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
212a0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
212b0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
212c0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
212d0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
212e0 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
212f0 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
21300 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
21310 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
21320 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
21330 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
21340 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
21350 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
21360 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
21370 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
21380 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
21390 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
213a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
213b0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
213c0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
213d0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
213e0 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
213f0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
21400 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
21410 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
21420 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
21430 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
21440 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
21450 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
21460 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
21470 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
21480 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
21490 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
214a0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
214b0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
214c0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
214d0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
214e0 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
214f0 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
21500 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
21510 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
21520 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
21530 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
21540 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
21550 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
21560 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
21570 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
21580 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
21590 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
215a0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
215b0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
215c0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
215d0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
215e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
215f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21600 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
21610 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
21620 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
21630 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
21640 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
21650 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
21660 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
21670 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
21680 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
21690 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
216a0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
216b0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
216c0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
216d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
216e0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
216f0 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
21700 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
21710 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
21720 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
21730 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
21740 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
21750 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
21760 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21770 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
21780 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
21790 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
217a0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
217b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
217c0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
217d0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
217e0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
217f0 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
21800 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
21810 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
21820 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
21830 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
21840 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
21850 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
21860 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
21870 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
21880 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
21890 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
218a0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
218b0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
218c0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
218d0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
218e0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
218f0 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
21900 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
21910 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
21920 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
21930 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
21940 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
21950 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
21960 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
21970 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
21980 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
21990 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
219a0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
219b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
219c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
219d0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
219e0 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
219f0 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
21a00 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
21a10 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
21a20 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
21a30 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
21a40 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
21a50 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
21a60 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
21a70 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
21a80 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21a90 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
21aa0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
21ab0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
21ac0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
21ad0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
21ae0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
21af0 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
21b00 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
21b10 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
21b20 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
21b30 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
21b40 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
21b50 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
21b60 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
21b70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
21b80 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
21b90 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
21ba0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
21bb0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
21bc0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
21bd0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
21be0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
21bf0 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
21c00 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21c10 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   flag..** </ul>.
21c20 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
21c30 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
21c40 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
21c50 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
21c60 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
21c70 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
21c80 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
21c90 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
21ca0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
21cb0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
21cc0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
21cd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
21ce0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
21cf0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
21d00 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
21d10 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
21d20 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
21d30 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
21d40 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
21d50 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
21d60 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
21d70 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
21d80 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
21d90 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
21da0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
21db0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
21dc0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
21dd0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
21de0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
21df0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
21e00 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
21e10 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
21e20 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
21e30 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
21e40 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
21e50 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
21e60 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
21e70 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
21e80 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
21e90 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
21ea0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
21eb0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
21ec0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
21ed0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
21ee0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
21ef0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
21f00 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
21f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
21f20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
21f30 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
21f40 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
21f50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
21f60 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
21f70 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
21f80 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
21f90 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
21fa0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
21fb0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
21fc0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
21fd0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
21fe0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
21ff0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
22000 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
22010 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
22020 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
22030 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
22040 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
22050 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
22060 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
22070 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
22080 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
22090 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
220a0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
220b0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
220c0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
220d0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
220e0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
220f0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
22100 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
22110 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
22120 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
22130 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
22140 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
22150 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
22160 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
22170 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
22180 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
22190 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
221a0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
221b0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
221c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
221d0 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  ?vfs=unix-nolock
221e0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
221f0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
22200 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
22210 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
22220 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f  l VFS "unix-nolo
22230 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ck"..** <tr><td>
22240 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
22250 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
22260 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
22270 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
22280 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
22290 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
222a0 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
222b0 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
222c0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
222d0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
222e0 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
222f0 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
22300 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
22310 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
22320 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
22330 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
22340 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
22350 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
22360 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
22370 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
22380 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
22390 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
223a0 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
223b0 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
223c0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
223d0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
223e0 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
223f0 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
22400 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
22410 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
22420 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
22430 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
22440 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
22450 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
22460 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
22470 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
22480 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
22490 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
224a0 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
224b0 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
224c0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
224d0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
224e0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
224f0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
22500 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
22510 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
22520 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
22530 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
22540 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
22550 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
22560 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
22570 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
22580 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
22590 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
225a0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
225b0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
225c0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
225d0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
225e0 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
225f0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
22600 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
22610 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
22620 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
22630 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
22640 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
22650 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
22660 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
22670 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
22680 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
22690 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
226a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
226b0 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
226c0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
226d0 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
226e0 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
226f0 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
22700 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
22710 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
22720 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
22730 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
22740 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
22750 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
22760 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
22770 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
22780 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
22790 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
227a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
227b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
227c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
227d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
227e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
227f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
22800 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22810 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
22820 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
22830 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
22840 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
22850 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
22860 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
22870 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
22880 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
22890 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
228a0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
228b0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
228c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
228d0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
228e0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
228f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
22900 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
22910 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
22920 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
22930 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
22940 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
22950 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
22960 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
22970 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
22980 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
22990 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
229a0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
229b0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
229c0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
229d0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
229e0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
229f0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
22a00 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
22a10 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
22a20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
22a30 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
22a40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
22a50 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
22a60 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22a70 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
22a80 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
22a90 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
22aa0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
22ab0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
22ac0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
22ad0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
22ae0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
22af0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
22b00 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
22b10 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
22b20 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
22b30 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
22b40 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
22b50 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
22b60 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
22b70 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
22b80 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
22b90 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
22ba0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
22bb0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
22bc0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
22bd0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
22be0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
22bf0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
22c00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22c10 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
22c20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
22c30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
22c40 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
22c50 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
22c60 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
22c70 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
22c80 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
22c90 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
22ca0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
22cb0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
22cc0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
22cd0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
22ce0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
22cf0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
22d00 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
22d10 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
22d20 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
22d30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22d40 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
22d50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
22d60 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
22d70 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
22d80 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
22d90 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
22da0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
22db0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
22dc0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
22dd0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
22de0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22df0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
22e00 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
22e10 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
22e20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
22e30 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
22e40 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
22e50 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
22e60 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
22e70 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
22e80 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
22e90 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
22ea0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
22eb0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
22ec0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
22ed0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
22ee0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
22ef0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
22f00 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22f10 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
22f20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
22f30 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
22f40 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
22f50 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
22f60 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
22f70 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
22f80 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
22f90 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
22fa0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
22fb0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
22fc0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
22fd0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
22fe0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
22ff0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
23000 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
23010 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
23020 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
23030 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
23040 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
23050 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
23060 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23070 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
23080 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
23090 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
230a0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
230b0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
230c0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
230d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
230e0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
230f0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
23100 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
23110 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
23120 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
23130 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
23140 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
23150 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
23160 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23170 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
23180 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
23190 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
231a0 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
231b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
231c0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
231d0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
231e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
231f0 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
23200 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
23210 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
23220 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
23230 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
23240 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
23250 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
23260 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
23270 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
23280 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
23290 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
232a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
232b0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
232c0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
232d0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
232e0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
232f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
23300 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
23310 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
23320 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
23330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23340 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
23350 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
23360 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
23370 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
23380 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
23390 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
233a0 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
233b0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
233c0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
233d0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
233e0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
233f0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
23400 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
23410 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
23420 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
23430 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
23440 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
23450 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
23460 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
23470 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
23480 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
23490 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
234a0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
234b0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
234c0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
234d0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
234e0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
234f0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
23500 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
23510 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
23520 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
23530 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
23540 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
23550 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
23560 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
23570 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
23580 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
23590 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
235a0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
235b0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
235c0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
235d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
235e0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
235f0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
23600 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
23610 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
23620 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
23630 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
23640 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
23650 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
23660 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
23670 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
23680 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
23690 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
236a0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
236b0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
236c0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
236d0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
236e0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
236f0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
23700 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
23710 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
23720 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
23730 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
23740 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
23750 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
23760 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
23770 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
23780 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
23790 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
237a0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
237b0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
237c0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
237d0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
237e0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
237f0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
23800 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
23810 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
23820 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
23830 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
23840 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
23850 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
23860 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
23870 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23880 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
23890 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
238a0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
238b0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
238c0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
238d0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
238e0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
238f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
23900 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
23910 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
23920 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
23930 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
23940 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
23950 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
23960 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
23970 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
23980 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
23990 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
239a0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
239b0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
239c0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
239d0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
239e0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
239f0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
23a00 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
23a10 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
23a20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
23a30 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
23a40 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
23a50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
23a60 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
23a70 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
23a80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
23a90 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
23aa0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  sg(sqlite3*);.SQ
23ab0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
23ac0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
23ad0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
23ae0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
23af0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23b00 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
23b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
23b20 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
23b30 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
23b40 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
23b50 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
23b60 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
23b70 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
23b80 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
23b90 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
23ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
23bb0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
23bc0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
23bd0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
23be0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
23bf0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
23c00 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
23c10 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
23c20 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
23c30 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
23c40 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
23c50 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
23c60 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
23c70 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
23c80 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
23c90 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
23ca0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
23cb0 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
23cc0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
23cd0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
23ce0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
23cf0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
23d00 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
23d10 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
23d20 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
23d30 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
23d40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23d50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
23d60 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
23d70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
23d80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
23d90 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
23da0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
23db0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
23dc0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
23dd0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
23de0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
23df0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
23e00 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
23e10 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
23e20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
23e30 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
23e40 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
23e50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
23e60 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
23e70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
23e80 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
23e90 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
23ea0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
23eb0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
23ec0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
23ed0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
23ee0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
23ef0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
23f00 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
23f10 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
23f20 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
23f30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23f40 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
23f50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23f60 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
23f70 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
23f80 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
23f90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
23fa0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
23fb0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
23fc0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
23fd0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
23fe0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
23ff0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
24000 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
24010 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
24020 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
24030 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
24040 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
24050 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
24060 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
24070 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
24080 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
24090 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
240a0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
240b0 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
240c0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
240d0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
240e0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
240f0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
24100 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
24110 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
24120 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
24130 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
24140 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
24150 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
24160 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
24170 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
24180 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
24190 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
241a0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
241b0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
241c0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
241d0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
241e0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
241f0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
24200 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
24210 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
24220 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
24230 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
24240 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24250 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
24260 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
24270 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
24280 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
24290 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
242a0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
242b0 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
242c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
242d0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
242e0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
242f0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
24300 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
24310 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
24320 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
24330 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
24340 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
24350 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
24360 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
24370 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
24380 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
24390 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
243a0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
243b0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
243c0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
243d0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
243e0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
243f0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
24400 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
24410 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
24420 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
24430 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
24440 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
24450 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
24460 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
24470 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
24480 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
24490 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
244a0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
244b0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
244c0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
244d0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
244e0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
244f0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
24500 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
24510 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
24520 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
24530 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
24540 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
24550 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
24560 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
24570 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
24580 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
24590 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
245a0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
245b0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
245c0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
245d0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
245e0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
245f0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
24600 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
24610 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
24620 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
24630 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
24640 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
24650 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
24660 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  I int sqlite3_li
24670 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
24680 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
24690 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
246a0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
246b0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
246c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
246d0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
246e0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
246f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24700 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
24710 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
24720 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
24730 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
24740 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
24750 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
24760 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
24770 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
24780 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
24790 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
247a0 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
247b0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
247c0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
247d0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
247e0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
247f0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
24800 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
24810 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
24820 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
24830 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24840 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
24850 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
24860 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
24870 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
24880 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24890 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
248a0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
248b0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
248c0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
248d0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
248e0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
248f0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
24900 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
24920 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
24930 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
24940 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24950 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24960 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
24970 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
24980 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
24990 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
249a0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
249b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
249c0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
249d0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
249e0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
249f0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
24a00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24a10 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24a20 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24a30 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24a40 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24a50 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
24a60 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
24a70 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
24a80 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
24a90 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24aa0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
24ab0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24ac0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
24ad0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
24ae0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
24af0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
24b00 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
24b10 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
24b20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24b30 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
24b40 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
24b50 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
24b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24b70 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24b80 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
24b90 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
24ba0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
24bb0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
24bc0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
24bd0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
24be0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
24bf0 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
24c00 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
24c10 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
24c20 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
24c30 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
24c40 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24c50 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
24c60 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
24c70 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
24c80 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
24c90 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24ca0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
24cb0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
24cc0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24cd0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
24ce0 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
24cf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
24d00 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
24d10 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24d20 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
24d30 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
24d40 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
24d50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24d60 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24d70 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
24d80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
24d90 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24da0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24db0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
24dc0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
24dd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
24de0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
24df0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
24e00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24e10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24e20 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
24e30 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24e40 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24e50 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
24e60 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
24e70 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
24e80 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
24e90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
24ea0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24eb0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
24ec0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
24ed0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
24ee0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
24ef0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24f00 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
24f10 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
24f20 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24f30 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
24f40 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
24f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24f60 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
24f70 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
24f80 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
24f90 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
24fa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
24fb0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
24fc0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
24fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
24fe0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
24ff0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
25000 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
25010 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
25020 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
25030 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
25040 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
25050 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
25060 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
25070 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
25080 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
25090 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
250a0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
250b0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
250c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
250d0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
250e0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
250f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25100 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
25110 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
25120 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25130 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
25140 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
25150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25160 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
25170 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
25180 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
25190 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
251a0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
251b0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
251c0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
251d0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
251e0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
251f0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
25200 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
25210 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
25220 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
25230 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
25240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
25250 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
25260 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
25270 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
25280 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
25290 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
252a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
252b0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
252c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
252d0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
252e0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
252f0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
25300 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
25310 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
25320 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
25330 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
25340 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
25350 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
25360 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
25370 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
25380 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
25390 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
253a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
253b0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
253c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
253d0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
253e0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
253f0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
25400 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
25410 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
25420 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
25430 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
25440 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
25450 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
25460 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
25470 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
25480 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
25490 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
254a0 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
254b0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
254c0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
254d0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
254e0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
254f0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
25500 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
25510 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
25520 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
25530 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
25540 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
25550 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
25560 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
25570 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
25580 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
25590 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
255a0 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
255b0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
255c0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
255d0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
255e0 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
255f0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
25600 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
25610 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
25620 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
25630 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
25640 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
25650 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
25660 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
25670 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
25680 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
25690 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
256a0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
256b0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
256c0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
256d0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
256e0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
256f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
25700 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
25710 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
25720 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
25730 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
25740 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
25750 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
25760 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
25770 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
25780 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
25790 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
257a0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
257b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
257c0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
257d0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
257e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
257f0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
25800 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
25810 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
25820 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
25830 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
25840 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
25850 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
25860 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
25870 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
25880 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
25890 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
258a0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
258b0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
258c0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
258d0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
258e0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
258f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25900 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
25910 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
25920 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
25930 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
25940 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
25950 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
25960 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
25970 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
25980 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
25990 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
259a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
259b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
259c0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
259d0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
259e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
259f0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
25a00 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
25a10 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
25a20 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
25a30 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
25a40 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
25a50 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
25a60 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
25a70 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
25a80 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
25a90 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
25aa0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
25ab0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
25ac0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
25ad0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
25ae0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
25af0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
25b00 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
25b10 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
25b20 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
25b30 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
25b40 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
25b50 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
25b60 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
25b70 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
25b80 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
25b90 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
25ba0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
25bb0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
25bc0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
25bd0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
25be0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
25bf0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
25c00 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
25c10 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
25c20 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
25c30 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
25c40 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
25c50 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
25c60 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
25c70 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
25c80 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
25c90 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
25ca0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
25cb0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
25cc0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
25cd0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
25ce0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25cf0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
25d00 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
25d10 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
25d20 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
25d30 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
25d40 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
25d50 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
25d60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
25d70 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
25d80 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
25d90 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
25da0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
25db0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
25dc0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
25dd0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
25de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25df0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
25e00 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
25e10 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
25e20 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
25e30 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
25e40 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
25e50 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
25e60 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
25e70 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25e80 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
25e90 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
25ea0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
25eb0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
25ec0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
25ed0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
25ee0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
25ef0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
25f00 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
25f10 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
25f20 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
25f30 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
25f40 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
25f50 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
25f60 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
25f70 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
25f80 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
25f90 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
25fa0 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
25fb0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
25fc0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
25fd0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
25fe0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
25ff0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
26000 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
26010 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
26020 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
26030 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
26040 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
26050 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
26060 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
26070 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
26080 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
26090 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
260a0 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
260b0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
260c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
260d0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
260e0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
260f0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
26100 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
26110 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
26120 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
26130 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
26140 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
26150 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26160 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
26170 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
26180 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
26190 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
261a0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
261b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
261c0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
261d0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
261e0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
261f0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
26200 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
26210 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
26220 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
26230 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26240 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26250 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
26260 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26270 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26280 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26290 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
262a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
262b0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
262c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
262d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
262e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
262f0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
26300 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
26310 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
26320 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
26330 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
26340 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
26350 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
26360 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
26370 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
26380 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
26390 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
263a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
263b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
263c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
263d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
263e0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
263f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26400 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
26410 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26420 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
26430 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26440 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
26450 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
26460 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
26470 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
26480 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
26490 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
264a0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
264b0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
264c0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
264d0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
264e0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
264f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
26500 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
26510 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
26520 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
26530 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
26540 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26550 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
26560 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
26570 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
26580 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
26590 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
265a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
265b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
265c0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
265d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
265e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
265f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
26600 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
26610 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
26620 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
26630 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
26640 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
26650 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
26660 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
26670 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
26680 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
26690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
266a0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
266b0 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
266c0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
266d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
266e0 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
266f0 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
26700 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
26710 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
26720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26730 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
26740 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
26750 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
26760 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
26770 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
26780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26790 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
267a0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
267b0 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
267c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
267d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
267e0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
267f0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
26800 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
26810 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  tabase.**.** ^Th
26820 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
26830 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
26840 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
26850 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
26860 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
26870 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26880 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
26890 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
268a0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
268b0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
268c0 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
268d0 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
268e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
268f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
26900 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
26910 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
26920 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
26930 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
26940 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
26950 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
26960 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
26970 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
26980 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
26990 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
269a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
269b0 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
269c0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
269d0 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
269e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
269f0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
26a00 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
26a10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
26a20 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
26a30 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
26a40 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
26a50 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
26a60 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
26a70 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
26a80 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
26a90 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
26aa0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
26ab0 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
26ac0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
26ad0 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
26ae0 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
26af0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
26b00 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
26b10 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
26b20 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
26b30 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
26b40 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
26b50 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
26b60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
26b70 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
26b80 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
26b90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
26ba0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
26bb0 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
26bc0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
26bd0 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
26be0 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
26bf0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
26c00 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
26c10 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
26c20 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
26c30 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
26c40 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
26c50 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
26c60 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
26c70 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
26c80 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
26c90 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
26ca0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
26cb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
26cc0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
26cd0 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
26ce0 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
26cf0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
26d00 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
26d10 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
26d20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
26d30 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
26d40 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
26d50 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
26d60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26d70 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
26d80 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
26d90 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
26da0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
26db0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
26dc0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
26dd0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
26de0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
26df0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26e00 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
26e10 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
26e20 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
26e30 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
26e40 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
26e50 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
26e60 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
26e70 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
26e80 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
26e90 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
26ea0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
26eb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
26ec0 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
26ed0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
26ee0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
26ef0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
26f00 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
26f10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
26f20 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
26f30 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
26f40 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
26f50 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
26f60 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
26f70 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
26f80 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
26f90 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
26fa0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
26fb0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
26fc0 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
26fd0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
26fe0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
26ff0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
27000 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
27010 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
27020 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
27030 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
27040 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
27050 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
27060 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
27070 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
27080 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
27090 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
270a0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
270b0 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  n open..*/.SQLIT
270c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
270d0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
270e0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
270f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
27100 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
27110 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
27120 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
27130 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27140 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
27150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
27160 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
27170 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
27180 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
27190 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
271a0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
271b0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
271c0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
271d0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
271e0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
271f0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
27200 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
27210 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
27220 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
27230 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
27240 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
27250 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
27260 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
27270 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
27280 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27290 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
272a0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
272b0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
272c0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
272d0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
272e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
272f0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
27300 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
27310 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
27320 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
27330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27340 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
27350 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
27360 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
27370 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
27380 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
27390 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
273a0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
273b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
273c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
273d0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
273e0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
273f0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
27400 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
27410 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
27420 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
27430 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
27440 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27450 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
27460 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
27470 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
27480 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27490 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
274a0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
274b0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
274c0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
274d0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
274e0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
274f0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
27500 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
27510 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
27520 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
27530 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
27540 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
27550 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
27560 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
27570 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
27580 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
27590 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
275a0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
275b0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
275c0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
275d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
275e0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
275f0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
27600 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
27610 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
27620 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
27630 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
27640 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
27650 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
27660 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
27670 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
27680 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
27690 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
276a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
276b0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
276c0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
276d0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
276e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
276f0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
27700 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
27710 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
27720 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
27730 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
27740 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27750 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
27760 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
27770 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27780 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
27790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
277a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
277b0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
277c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
277d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
277e0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
277f0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
27800 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
27810 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27820 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
27830 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
27840 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
27850 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
27860 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
27870 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
27880 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
27890 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
278a0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
278b0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
278c0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
278d0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
278e0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
278f0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
27900 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
27910 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
27920 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
27930 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
27940 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
27950 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
27960 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
27970 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
27980 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
27990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
279a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
279b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
279c0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
279d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
279e0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
279f0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
27a00 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
27a10 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
27a20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
27a30 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
27a40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
27a50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
27a60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27a70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
27a80 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
27a90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
27aa0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
27ab0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
27ac0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
27ad0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
27ae0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
27af0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
27b00 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
27b10 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
27b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
27b30 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
27b40 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27b50 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
27b60 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
27b70 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
27b80 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
27b90 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
27ba0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
27bb0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
27bc0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
27bd0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
27be0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
27bf0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
27c00 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
27c10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
27c20 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
27c30 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
27c40 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
27c50 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
27c60 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
27c70 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
27c80 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
27c90 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
27ca0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
27cb0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
27cc0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
27cd0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
27ce0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
27cf0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
27d00 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
27d10 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
27d20 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
27d30 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
27d40 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
27d50 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
27d60 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
27d70 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
27d80 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
27d90 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
27da0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
27db0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
27dc0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
27dd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27de0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
27df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
27e00 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
27e10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
27e20 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
27e30 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
27e40 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
27e50 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
27e60 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
27e70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27e80 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
27e90 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
27ea0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
27eb0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
27ec0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
27ed0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
27ee0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
27ef0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
27f00 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
27f10 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
27f20 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
27f30 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
27f40 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
27f50 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
27f60 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
27f70 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
27f80 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
27f90 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
27fa0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
27fb0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
27fc0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
27fd0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
27fe0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
27ff0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28000 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
28010 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
28020 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
28030 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
28040 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
28050 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
28060 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
28070 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
28080 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
28090 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
280a0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
280b0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
280c0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
280d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
280e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
280f0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
28100 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
28110 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
28120 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
28130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28140 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
28150 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
28160 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
28170 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
28180 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
28190 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
281a0 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
281b0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
281c0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
281d0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
281e0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
281f0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
28200 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
28210 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
28220 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
28230 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
28240 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
28250 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
28260 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
28270 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
28280 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
28290 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
282a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
282b0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
282c0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
282d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
282e0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
282f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28300 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
28310 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
28320 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
28330 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
28340 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
28350 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
28360 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
28370 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
28380 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
28390 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
283a0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
283b0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
283c0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
283d0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
283e0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
283f0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
28400 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
28410 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
28420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28430 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
28440 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
28450 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
28460 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
28470 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
28480 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
28490 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
284a0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
284b0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
284c0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
284d0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
284e0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
284f0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
28500 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28510 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
28520 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
28530 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
28540 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
28550 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
28560 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
28570 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
28580 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
28590 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
285a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
285b0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
285c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
285d0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
285e0 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
285f0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
28600 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
28610 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
28620 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
28630 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
28640 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
28650 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
28660 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
28670 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
28680 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
28690 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
286a0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
286b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
286c0 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
286d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
286e0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
286f0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
28700 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
28710 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
28720 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
28730 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
28740 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
28750 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
28760 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
28770 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
28780 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
28790 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
287a0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
287b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
287c0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
287d0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
287e0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
287f0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
28800 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
28810 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
28820 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
28830 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
28840 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
28850 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
28860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28870 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
28880 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
28890 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
288a0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
288b0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
288c0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
288d0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
288e0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
288f0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
28900 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
28910 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
28920 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
28930 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
28940 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
28950 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
28960 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
28970 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
28980 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
28990 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
289a0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
289b0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
289c0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
289d0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
289e0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
289f0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
28a00 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
28a10 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
28a20 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
28a30 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28a40 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
28a50 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
28a60 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
28a70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28a80 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
28a90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
28aa0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
28ab0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
28ac0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
28ad0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
28ae0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28af0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
28b00 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
28b10 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
28b20 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
28b30 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
28b40 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
28b50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28b60 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
28b70 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
28b80 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
28b90 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
28ba0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
28bb0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
28bc0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
28bd0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
28be0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
28bf0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
28c00 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
28c10 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
28c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28c30 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
28c40 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
28c50 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
28c60 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
28c70 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
28c80 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
28c90 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
28ca0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
28cb0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
28cc0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
28cd0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
28ce0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
28cf0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
28d00 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
28d10 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
28d20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28d30 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
28d40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28d50 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
28d60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
28d70 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
28d80 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
28d90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28da0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
28db0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28dc0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
28dd0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28de0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28df0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
28e00 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
28e10 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
28e20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28e30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
28e40 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
28e50 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c  , int, int);.SQL
28e60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28e70 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
28e80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28e90 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
28ea0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28eb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
28ec0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
28ed0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
28ee0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28ef0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
28f00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28f10 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
28f20 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28f30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28f40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
28f50 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
28f60 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
28f70 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
28f80 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
28f90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28fa0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
28fb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28fc0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
28fd0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
28fe0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28ff0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
29000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29010 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
29020 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
29030 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
29040 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
29050 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
29060 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
29070 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
29080 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
29090 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
290a0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
290b0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
290c0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
290d0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
290e0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
290f0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
29100 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
29110 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
29120 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
29130 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
29140 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
29150 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
29160 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
29170 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
29180 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
29190 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
291a0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
291b0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
291c0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
291d0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
291e0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
291f0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
29200 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
29210 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
29220 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
29230 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
29240 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
29250 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
29260 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
29270 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29280 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29290 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
292a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
292b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
292c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
292d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
292e0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
292f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29310 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
29320 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
29330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
29340 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
29350 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
29360 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
29370 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
29380 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
29390 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
293a0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
293b0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
293c0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
293d0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
293e0 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
293f0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
29400 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
29410 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
29420 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
29430 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
29440 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
29450 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
29460 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
29470 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
29480 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
29490 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
294a0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
294b0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
294c0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
294d0 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
294e0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
294f0 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
29500 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
29510 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
29520 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
29530 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
29540 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
29550 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
29560 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
29570 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
29580 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
29590 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
295a0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
295b0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
295c0 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
295d0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
295e0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
295f0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
29600 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
29610 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
29620 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
29630 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
29640 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
29650 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
29660 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
29670 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
29680 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
29690 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
296a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
296b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
296c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
296d0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
296e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
296f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
29700 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
29710 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29720 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
29730 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29740 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29750 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29760 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
29770 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
29780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
29790 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
297a0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
297b0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
297c0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
297d0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
297e0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
297f0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
29800 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
29810 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
29820 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
29830 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
29840 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29850 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29860 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
29870 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
29880 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
29890 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
298a0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
298b0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
298c0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
298d0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
298e0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
298f0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
29900 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
29910 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
29920 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
29930 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29940 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29950 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29960 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29970 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29980 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
29990 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
299a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
299b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
299c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
299d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
299e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
299f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
29a00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29a10 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
29a20 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
29a30 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
29a40 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
29a50 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
29a60 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
29a70 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
29a80 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
29a90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29aa0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
29ab0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
29ac0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
29ad0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
29ae0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
29af0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
29b00 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
29b10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29b20 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
29b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
29b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29b50 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
29b60 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
29b70 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
29b80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
29b90 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
29ba0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
29bb0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
29bc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29bd0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
29be0 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
29bf0 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
29c00 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
29c10 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
29c20 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
29c30 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
29c40 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29c50 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29c60 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
29c70 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
29c80 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
29c90 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
29ca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29cb0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
29cc0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
29cd0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
29ce0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
29cf0 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
29d00 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
29d10 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
29d20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
29d30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
29d40 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
29d50 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
29d60 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
29d70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
29d80 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
29d90 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
29da0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
29db0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
29dc0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
29dd0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
29de0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
29df0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
29e00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
29e10 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
29e20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
29e30 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
29e40 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
29e50 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
29e60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
29e70 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
29e80 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
29e90 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
29ea0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
29eb0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29ec0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
29ed0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
29ee0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29ef0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
29f00 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
29f10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29f20 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
29f30 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
29f40 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
29f50 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
29f60 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
29f70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
29f80 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
29f90 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
29fa0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
29fb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
29fc0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
29fd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
29fe0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
29ff0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
2a000 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
2a010 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
2a020 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
2a030 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
2a040 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
2a050 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
2a060 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
2a070 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
2a080 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
2a090 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2a0a0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
2a0b0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
2a0c0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
2a0d0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
2a0e0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
2a0f0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
2a100 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
2a110 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
2a120 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
2a130 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2a140 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
2a150 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
2a160 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
2a170 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
2a180 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
2a190 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2a1a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a1b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2a1c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a1d0 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
2a1e0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2a1f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a200 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a210 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2a220 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2a230 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2a240 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2a250 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2a260 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2a270 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2a280 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2a290 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2a2a0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2a2b0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2a2c0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2a2d0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2a2e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2a2f0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2a300 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2a310 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2a320 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2a330 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2a340 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2a350 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2a360 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2a370 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2a380 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2a390 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2a3a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2a3b0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2a3c0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2a3d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a3e0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2a3f0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2a400 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2a410 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2a420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a430 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2a440 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2a450 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2a460 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2a470 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2a480 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2a490 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2a4a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a4b0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2a4c0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2a4d0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2a4e0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2a4f0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2a500 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2a510 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2a520 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2a530 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2a540 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2a550 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2a560 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2a570 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2a580 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2a590 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2a5a0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2a5b0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2a5c0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2a5d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2a5e0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2a5f0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2a600 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2a610 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2a620 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2a630 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2a640 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2a650 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2a660 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2a670 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2a680 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2a690 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2a6a0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2a6b0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2a6c0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2a6d0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2a6e0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2a6f0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2a700 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2a710 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2a720 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2a730 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2a740 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2a750 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2a760 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2a770 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2a780 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2a790 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2a7a0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2a7b0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2a7c0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2a7d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2a7e0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2a7f0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2a800 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2a810 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2a820 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2a830 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2a840 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2a850 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2a860 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2a870 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2a880 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2a890 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2a8a0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2a8b0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2a8c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2a8d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2a8e0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2a8f0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2a900 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2a910 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2a920 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2a930 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2a940 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2a950 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2a960 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2a970 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2a980 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2a990 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2a9a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2a9b0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2a9c0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2a9d0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2a9e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2a9f0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2aa00 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2aa10 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2aa20 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2aa30 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2aa40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2aa50 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2aa60 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2aa70 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2aa80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2aa90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2aaa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2aab0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2aac0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2aad0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2aae0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2aaf0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2ab00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ab10 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2ab20 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2ab30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2ab40 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2ab50 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2ab60 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2ab70 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2ab80 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2ab90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2aba0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2abb0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2abc0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2abd0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2abe0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2abf0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2ac00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2ac10 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
2ac20 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ac30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac40 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
2ac50 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
2ac60 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
2ac70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2ac80 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2ac90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2aca0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2acb0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2acc0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2acd0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2ace0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2acf0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2ad00 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2ad10 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2ad20 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2ad30 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2ad40 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2ad50 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2ad60 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2ad70 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2ad80 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2ad90 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2ada0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2adb0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2adc0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2add0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2ade0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2adf0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2ae00 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2ae10 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2ae20 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2ae30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2ae40 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2ae50 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2ae60 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2ae70 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2ae80 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2ae90 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2aea0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2aeb0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2aec0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2aed0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2aee0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2aef0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2af00 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2af10 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2af20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2af30 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2af40 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2af50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2af60 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2af70 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2af80 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2af90 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2afa0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2afb0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2afc0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2afd0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2afe0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2aff0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2b000 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2b010 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2b020 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2b030 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2b040 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2b050 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2b060 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2b070 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2b080 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2b090 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2b0a0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2b0b0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2b0c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2b0d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b0e0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2b0f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b100 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2b110 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2b120 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2b130 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2b140 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2b150 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2b160 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2b170 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
2b180 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b190 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2b1a0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2b1b0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2b1c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b1d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2b1e0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2b1f0 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2b200 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2b210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b220 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2b230 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2b240 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2b250 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2b260 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2b270 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2b280 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2b290 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2b2a0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2b2b0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2b2c0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2b2d0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2b2e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2b2f0 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2b300 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2b310 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2b320 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b330 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2b340 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b350 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2b360 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2b370 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2b380 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2b390 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2b3a0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2b3b0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2b3c0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2b3d0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2b3e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2b3f0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2b400 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2b410 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2b420 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2b430 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2b440 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2b450 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2b460 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2b470 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2b480 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2b490 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2b4a0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2b4b0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2b4c0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2b4d0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2b4e0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2b4f0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2b500 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2b510 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2b520 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2b530 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2b540 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2b550 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2b560 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2b570 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2b580 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2b590 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2b5a0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2b5b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2b5c0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2b5d0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2b5e0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2b5f0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2b600 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2b610 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2b620 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2b630 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2b640 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2b650 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2b660 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2b670 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2b680 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2b690 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2b6a0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2b6b0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2b6c0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2b6d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2b6e0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2b6f0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2b700 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2b710 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2b720 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2b730 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2b740 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2b750 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2b760 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b770 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2b780 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2b790 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2b7a0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2b7b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2b7c0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2b7d0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2b7e0 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2b7f0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2b800 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2b810 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2b820 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2b830 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2b840 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2b850 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2b860 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2b870 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2b880 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2b890 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2b8a0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2b8b0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2b8c0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2b8d0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2b8e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2b8f0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2b900 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2b910 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2b920 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2b930 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2b940 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2b950 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2b960 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2b970 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2b980 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2b990 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2b9a0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2b9b0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2b9c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2b9d0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2b9e0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2b9f0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2ba00 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2ba10 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2ba20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2ba30 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2ba40 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2ba50 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2ba60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ba70 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2ba80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2ba90 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2baa0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2bab0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2bac0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2bad0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2bae0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2baf0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2bb00 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2bb10 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2bb20 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2bb30 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2bb40 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2bb50 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2bb60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bb70 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2bb80 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2bb90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2bba0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2bbb0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2bbc0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2bbd0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2bbe0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2bbf0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2bc00 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2bc10 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2bc20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bc30 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2bc40 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2bc50 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2bc60 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2bc70 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2bc80 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2bc90 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2bca0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2bcb0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2bcc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2bcd0 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2bce0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2bcf0 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2bd00 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2bd10 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2bd20 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2bd30 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2bd40 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2bd50 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2bd60 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2bd70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bd80 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2bd90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bda0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2bdb0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2bdc0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2bdd0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2bde0 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2bdf0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2be00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2be10 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2be20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2be30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2be40 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2be50 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2be60 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2be70 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2be80 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2be90 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2bea0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2beb0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2bec0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2bed0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2bee0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2bef0 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2bf00 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2bf10 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2bf20 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2bf30 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2bf40 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2bf50 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2bf60 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2bf70 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2bf80 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2bf90 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2bfa0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2bfb0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2bfc0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2bfd0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2bfe0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2bff0 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2c000 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2c010 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2c020 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2c030 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2c040 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2c050 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c060 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2c070 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2c080 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2c090 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2c0a0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2c0b0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2c0c0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2c0d0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2c0e0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2c0f0 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2c100 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2c110 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2c120 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c130 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2c140 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2c150 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2c160 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2c170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c180 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2c190 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2c1a0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2c1b0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2c1c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2c1d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c1e0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2c1f0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2c200 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2c210 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2c220 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2c230 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2c240 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2c250 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2c260 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2c270 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nded..*/.SQLITE_
2c280 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2c290 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2c2a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2c2b0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2c2c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2c2d0 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2c2e0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2c2f0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2c300 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2c310 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c320 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2c330 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2c340 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2c350 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c360 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2c370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2c380 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2c390 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2c3a0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2c3b0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2c3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2c3d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c3e0 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2c3f0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2c400 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2c410 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2c420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2c430 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2c440 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2c450 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2c460 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2c470 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2c480 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2c490 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2c4a0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2c4b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2c4c0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2c4d0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2c4e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2c4f0 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2c500 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2c510 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2c520 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c530 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2c540 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2c550 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2c560 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2c570 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2c580 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2c590 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2c5a0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2c5b0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2c5c0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2c5d0 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2c5e0 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2c5f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c600 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c610 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2c620 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2c630 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
2c640 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2c650 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2c660 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
2c670 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
2c680 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2c690 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
2c6a0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
2c6b0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
2c6c0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
2c6d0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
2c6e0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
2c6f0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2c700 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
2c710 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
2c720 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
2c730 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
2c740 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
2c750 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
2c760 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2c770 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2c780 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2c790 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2c7a0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2c7b0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2c7c0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2c7d0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2c7e0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2c7f0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2c800 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2c810 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2c820 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2c830 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c840 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2c850 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2c860 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2c870 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2c880 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2c890 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2c8a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c8b0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2c8c0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2c8d0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2c8e0 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2c8f0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2c900 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2c910 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2c920 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2c930 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2c940 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2c950 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2c960 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2c970 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2c980 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
2c990 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
2c9a0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2c9b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2c9c0 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
2c9d0 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
2c9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2c9f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
2ca00 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2ca10 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
2ca20 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
2ca30 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
2ca40 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
2ca50 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
2ca60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
2ca70 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2ca80 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ca90 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
2caa0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
2cab0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2cac0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
2cad0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
2cae0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2caf0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2cb00 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
2cb10 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
2cb20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2cb30 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2cb40 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
2cb50 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
2cb60 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
2cb70 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
2cb80 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2cb90 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
2cba0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
2cbb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2cbc0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2cbd0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
2cbe0 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
2cbf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2cc00 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
2cc10 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2cc20 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
2cc30 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
2cc40 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
2cc50 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
2cc60 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2cc70 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
2cc80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2cc90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2cca0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
2ccb0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
2ccc0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2ccd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2cce0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2ccf0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
2cd00 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
2cd10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2cd20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
2cd30 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
2cd40 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
2cd50 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
2cd60 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2cd70 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
2cd80 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
2cd90 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2cda0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2cdb0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
2cdc0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2cdd0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
2cde0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
2cdf0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
2ce00 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2ce10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2ce20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ce30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2ce40 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2ce50 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
2ce60 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2ce70 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
2ce80 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
2ce90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2cea0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
2ceb0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2cec0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2ced0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2cee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2cef0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2cf00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2cf10 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2cf20 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
2cf30 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
2cf40 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
2cf50 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
2cf60 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
2cf70 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2cf80 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
2cf90 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2cfa0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
2cfb0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
2cfc0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
2cfd0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
2cfe0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2cff0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2d000 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
2d010 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
2d020 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
2d030 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
2d040 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
2d050 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
2d060 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
2d070 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
2d080 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2d090 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
2d0a0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
2d0b0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2d0c0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
2d0d0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2d0e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2d0f0 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
2d100 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
2d110 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
2d120 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2d130 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
2d140 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2d150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d160 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
2d170 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2d180 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2d190 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2d1a0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2d1b0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2d1c0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2d1d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d1e0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2d1f0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2d200 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2d210 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2d220 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2d230 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d240 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2d250 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d260 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
2d270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2d280 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2d290 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2d2a0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
2d2b0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2d2c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d2d0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2d2e0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2d2f0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2d300 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2d310 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
2d320 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2d330 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d340 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
2d350 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
2d360 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d370 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
2d380 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2d390 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d3a0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2d3b0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2d3c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d3d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
2d3e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2d3f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
2d400 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2d410 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
2d420 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2d430 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d440 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2d450 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2d460 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2d470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d480 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
2d490 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2d4a0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2d4b0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2d4c0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
2d4d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2d4e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d4f0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2d500 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2d510 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2d520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d530 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
2d540 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
2d550 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2d560 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2d570 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2d580 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
2d590 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2d5a0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
2d5b0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2d5c0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
2d5d0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
2d5e0 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
2d5f0 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
2d600 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2d610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d620 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d630 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d640 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
2d650 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
2d660 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
2d670 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2d680 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
2d690 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
2d6a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2d6b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
2d6c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d6d0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
2d6e0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
2d6f0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
2d700 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
2d710 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
2d720 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
2d730 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
2d740 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2d750 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
2d760 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2d770 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2d780 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2d790 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2d7a0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2d7b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d7c0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
2d7d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2d7e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
2d7f0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
2d800 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
2d810 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
2d820 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
2d830 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
2d840 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
2d850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d860 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
2d870 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2d880 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2d890 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
2d8a0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
2d8b0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
2d8c0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2d8d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d8e0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
2d8f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2d900 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2d910 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
2d920 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2d930 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2d940 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d950 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
2d960 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2d970 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
2d980 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
2d990 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2d9a0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2d9b0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2d9c0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2d9d0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2d9e0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2d9f0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2da00 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2da10 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2da20 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2da30 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
2da40 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
2da50 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
2da60 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
2da70 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
2da80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2da90 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2daa0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
2dab0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
2dac0 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
2dad0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
2dae0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
2daf0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2db00 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2db10 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
2db20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2db30 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2db40 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2db50 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
2db60 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2db70 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
2db80 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
2db90 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2dba0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2dbb0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
2dbc0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
2dbd0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2dbe0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2dbf0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2dc00 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
2dc10 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
2dc20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2dc30 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2dc40 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2dc50 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
2dc60 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
2dc70 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2dc80 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2dc90 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
2dca0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2dcb0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
2dcc0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2dcd0 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
2dce0 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
2dcf0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2dd00 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2dd10 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2dd20 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
2dd30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2dd40 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
2dd50 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2dd60 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
2dd70 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2dd80 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2dd90 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
2dda0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2ddb0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
2ddc0 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
2ddd0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2dde0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2ddf0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
2de00 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
2de10 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2de20 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2de30 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2de40 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
2de50 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2de60 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
2de70 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2de80 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2de90 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
2dea0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2deb0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2dec0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
2ded0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
2dee0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
2def0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2df00 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
2df10 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
2df20 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
2df30 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
2df40 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
2df50 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
2df60 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
2df70 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
2df80 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
2df90 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
2dfa0 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
2dfb0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
2dfc0 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
2dfd0 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
2dfe0 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
2dff0 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
2e000 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
2e010 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
2e020 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
2e030 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
2e040 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
2e050 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
2e060 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
2e070 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
2e080 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2e090 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e0a0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
2e0b0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
2e0c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2e0d0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
2e0e0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2e0f0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
2e100 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
2e110 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
2e120 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
2e130 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
2e140 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2e150 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2e160 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
2e170 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
2e180 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2e190 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2e1a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e1b0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
2e1c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
2e1d0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
2e1e0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
2e1f0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
2e200 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2e210 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2e220 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
2e230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e240 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
2e250 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2e260 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2e270 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2e280 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2e290 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2e2a0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
2e2b0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2e2c0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2e2d0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
2e2e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e2f0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
2e300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e310 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
2e320 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2e330 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2e340 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
2e350 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
2e360 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
2e370 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
2e380 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
2e390 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
2e3a0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
2e3b0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
2e3c0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
2e3d0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
2e3e0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
2e3f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
2e400 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
2e410 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
2e420 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
2e430 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2e440 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2e450 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2e460 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2e470 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2e480 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2e490 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2e4a0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2e4b0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2e4c0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2e4d0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2e4e0 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2e4f0 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2e500 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2e510 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2e520 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2e530 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2e540 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2e550 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2e560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e570 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2e580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e590 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2e5a0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2e5b0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
2e5c0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2e5d0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2e5e0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2e5f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2e600 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2e610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e620 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
2e630 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
2e640 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
2e650 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
2e660 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
2e670 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2e680 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
2e690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e6a0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
2e6b0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
2e6c0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
2e6d0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
2e6e0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2e6f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2e700 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2e710 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
2e720 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
2e730 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
2e740 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
2e750 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
2e760 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
2e770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e780 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
2e790 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2e7a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
2e7b0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
2e7c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e7d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
2e7e0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
2e7f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e800 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
2e810 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2e820 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
2e830 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
2e840 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
2e850 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
2e860 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
2e870 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2e880 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2e890 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2e8a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
2e8b0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
2e8c0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
2e8d0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
2e8e0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
2e8f0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
2e900 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
2e910 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
2e920 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2e930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e940 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
2e950 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e960 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
2e970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
2e980 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
2e990 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2e9a0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
2e9b0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
2e9c0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
2e9d0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2e9e0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
2e9f0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
2ea00 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
2ea10 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
2ea20 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
2ea30 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
2ea40 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
2ea50 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2ea60 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
2ea70 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2ea80 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
2ea90 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
2eaa0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
2eab0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2eac0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2ead0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2eae0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2eaf0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2eb00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2eb10 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2eb20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2eb30 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2eb40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2eb50 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2eb60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2eb70 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2eb80 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2eb90 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2eba0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ebb0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2ebc0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2ebd0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2ebe0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2ebf0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
2ec00 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2ec10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2ec20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ec30 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2ec40 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
2ec50 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2ec60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2ec70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ec80 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2ec90 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2eca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ecb0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2ecc0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ecd0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2ece0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2ecf0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2ed00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2ed10 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
2ed20 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
2ed30 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
2ed40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ed50 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
2ed60 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
2ed70 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2ed80 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2ed90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2eda0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
2edb0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
2edc0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
2edd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2ede0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2edf0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2ee00 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
2ee10 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
2ee20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
2ee30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2ee40 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
2ee50 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
2ee60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
2ee70 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
2ee80 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
2ee90 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2eea0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
2eeb0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
2eec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
2eed0 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
2eee0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
2eef0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
2ef00 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
2ef10 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2ef20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2ef30 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
2ef40 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2ef50 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2ef60 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
2ef70 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
2ef80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
2ef90 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
2efa0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
2efb0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
2efc0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
2efd0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2efe0 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
2eff0 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
2f000 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2f010 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
2f020 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2f030 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2f040 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
2f050 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
2f060 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
2f070 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
2f080 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2f090 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
2f0a0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
2f0b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
2f0c0 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
2f0d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f0e0 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
2f0f0 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
2f100 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
2f110 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
2f120 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2f130 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
2f140 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
2f150 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2f160 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2f170 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
2f180 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
2f190 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2f1a0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2f1b0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
2f1c0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
2f1d0 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
2f1e0 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
2f1f0 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
2f200 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
2f210 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2f220 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2f230 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2f240 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2f250 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2f260 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2f270 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2f280 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f290 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2f2a0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2f2b0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2f2c0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2f2d0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2f2e0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2f2f0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2f300 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2f310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2f320 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2f330 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2f340 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2f350 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2f360 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2f370 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2f380 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2f390 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2f3a0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2f3b0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2f3c0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2f3d0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2f3e0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2f3f0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2f400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f410 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2f420 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2f430 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2f440 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2f450 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2f460 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2f470 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2f480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f490 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2f4a0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2f4b0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2f4c0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2f4d0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2f4e0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2f4f0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2f500 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2f510 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2f520 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2f530 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2f540 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2f550 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2f560 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2f570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f580 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2f590 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2f5a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2f5b0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2f5c0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2f5d0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2f5e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f5f0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2f600 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2f610 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2f620 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2f630 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2f640 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2f650 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2f660 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2f670 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2f680 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2f690 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2f6a0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2f6b0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2f6c0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2f6d0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2f6e0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2f6f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2f700 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f710 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2f720 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2f730 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f740 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2f750 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2f760 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2f770 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2f780 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2f790 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2f7a0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2f7b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2f7c0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2f7d0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2f7e0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2f7f0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2f800 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2f810 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2f820 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
2f830 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
2f840 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
2f850 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
2f860 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
2f870 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f880 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
2f890 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2f8a0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
2f8b0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
2f8c0 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
2f8d0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2f8e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
2f8f0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2f900 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2f910 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2f920 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2f930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2f940 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2f950 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2f960 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
2f970 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
2f980 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2f990 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2f9a0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
2f9b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f9c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2f9d0 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
2f9e0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
2f9f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
2fa00 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
2fa10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2fa20 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
2fa30 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2fa40 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
2fa50 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
2fa60 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
2fa70 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2fa80 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2fa90 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
2faa0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
2fab0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
2fac0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2fad0 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
2fae0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
2faf0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2fb00 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
2fb10 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
2fb20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
2fb30 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
2fb40 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
2fb50 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
2fb60 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
2fb70 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
2fb80 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
2fb90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2fba0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
2fbb0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
2fbc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2fbd0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2fbe0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2fbf0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2fc00 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
2fc10 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
2fc20 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2fc30 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2fc40 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2fc50 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2fc60 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
2fc70 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
2fc80 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
2fc90 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2fca0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2fcb0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
2fcc0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
2fcd0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
2fce0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2fcf0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
2fd00 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
2fd10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2fd20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
2fd30 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2fd40 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2fd50 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2fd60 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2fd70 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2fd80 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2fd90 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2fda0 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e  .  Every SQL fun
2fdb0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2fdc0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c  tion must be abl
2fdd0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
2fde0 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2fdf0 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2fe00 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2fe10 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2fe20 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2fe30 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2fe40 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2fe50 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  r.  ^An applicat
2fe60 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b  ion may.** invok
2fe70 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2fe80 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2fe90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fea0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2feb0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2fec0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2fed0 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2fee0 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2fef0 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57   eTextRep..** ^W
2ff00 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
2ff10 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2ff20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2ff30 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
2ff40 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
2ff50 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
2ff60 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
2ff70 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2ff80 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
2ff90 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
2ffa0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
2ffb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
2ffc0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
2ffd0 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
2ffe0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
2fff0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
30000 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
30010 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
30020 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
30030 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
30040 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
30050 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
30060 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
30070 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
30080 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
30090 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
300a0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
300b0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
300c0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
300d0 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
300e0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
300f0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
30100 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
30110 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
30120 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
30130 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
30140 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
30150 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
30160 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
30170 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
30180 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30190 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
301a0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
301b0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
301c0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
301d0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
301e0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
301f0 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
30200 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
30210 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
30220 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
30230 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
30240 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
30250 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
30260 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
30270 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
30280 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
30290 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
302a0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
302b0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
302c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
302d0 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
302e0 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
302f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
30300 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30310 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
30320 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
30330 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
30340 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30350 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
30360 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
30370 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
30380 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
30390 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
303a0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
303b0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
303c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
303d0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
303e0 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
303f0 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
30400 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
30410 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
30420 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
30430 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
30440 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
30450 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
30460 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
30470 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
30480 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
30490 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
304a0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
304b0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
304c0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
304d0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
304e0 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
304f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
30500 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
30510 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
30520 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
30530 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
30540 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
30550 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
30560 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
30570 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
30580 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
30590 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
305a0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
305b0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
305c0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
305d0 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
305e0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
305f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
30600 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
30610 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
30620 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
30630 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30640 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
30650 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
30660 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
30670 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
30680 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
30690 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
306a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
306b0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
306c0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
306d0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
306e0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
306f0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
30700 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
30710 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
30720 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
30730 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
30740 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30750 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
30760 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
30770 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
30780 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
30790 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
307a0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
307b0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
307c0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
307d0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
307e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
307f0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
30800 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
30810 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
30820 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
30830 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
30840 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
30850 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30860 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
30870 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
30880 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30890 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
308a0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
308b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
308c0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
308d0 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
308e0 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
308f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30900 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
30910 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
30920 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
30930 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
30940 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
30950 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
30960 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
30970 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
30980 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
30990 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
309a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
309b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
309c0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
309d0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
309e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
309f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30a00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30a10 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
30a20 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
30a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
30a40 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
30a50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30a60 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
30a70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
30a80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
30a90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
30aa0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
30ab0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
30ac0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
30ad0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
30ae0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
30af0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
30b00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
30b10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
30b20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
30b30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
30b40 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
30b50 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
30b60 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
30b70 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
30b80 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30b90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30ba0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
30bb0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
30bc0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
30bd0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
30be0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
30bf0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
30c00 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
30c10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
30c20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
30c30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
30c40 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
30c50 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30c60 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30c70 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
30c80 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
30c90 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
30ca0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
30cb0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
30cc0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
30cd0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
30ce0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
30cf0 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
30d00 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
30d10 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
30d20 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
30d30 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
30d40 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
30d50 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
30d60 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
30d70 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
30d80 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
30d90 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
30da0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
30db0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
30dc0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
30dd0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
30de0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
30df0 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
30e00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30e10 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
30e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
30e30 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
30e40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
30e50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
30e60 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
30e70 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
30e80 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
30e90 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
30ea0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
30eb0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
30ec0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
30ed0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
30ee0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
30ef0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
30f00 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
30f10 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
30f20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
30f30 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
30f40 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
30f50 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
30f60 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
30f70 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
30f80 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
30f90 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
30fa0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
30fb0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
30fc0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
30fd0 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
30fe0 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
30ff0 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
31000 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  D.SQLITE_API SQL
31010 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
31020 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
31030 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
31040 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
31050 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
31060 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31070 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
31080 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
31090 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
310a0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
310b0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
310c0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
310d0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
310e0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
310f0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
31100 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31110 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
31120 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
31130 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
31140 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
31150 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
31160 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
31170 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
31180 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
31190 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
311a0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
311b0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
311c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
311d0 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
311e0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
311f0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
31200 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
31210 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
31220 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
31230 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
31240 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31250 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
31260 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
31270 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
31280 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
31290 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
312a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
312b0 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
312c0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
312d0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
312e0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
312f0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
31300 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
31310 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
31320 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
31330 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31340 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
31350 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31360 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
31370 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
31380 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
31390 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
313a0 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
313b0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
313c0 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
313d0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
313e0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
313f0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
31400 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31410 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
31420 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
31430 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
31440 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
31450 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
31460 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
31470 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
31480 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
31490 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
314a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
314b0 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
314c0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
314d0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
314e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
314f0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
31500 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
31510 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
31520 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
31530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31540 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
31550 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
31560 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
31570 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
31580 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
31590 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
315a0 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
315b0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
315c0 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
315d0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
315e0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
315f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31600 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
31610 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
31620 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
31630 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
31640 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
31650 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
31660 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
31670 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
31680 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
31690 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
316a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
316b0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
316c0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
316d0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
316e0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
316f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
31700 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
31710 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
31720 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
31730 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
31740 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
31750 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
31760 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
31770 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
31780 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
31790 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
317a0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
317b0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
317c0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
317d0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
317e0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
317f0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
31800 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
31810 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
31820 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
31830 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
31840 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
31850 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
31860 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
31870 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
31880 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
31890 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
318a0 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
318b0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
318c0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
318d0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
318e0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
318f0 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
31900 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
31910 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
31920 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
31930 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
31940 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
31950 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
31960 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
31970 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
31980 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
31990 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
319a0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
319b0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
319c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
319d0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
319e0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
319f0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
31a00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
31a10 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
31a20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
31a30 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
31a40 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
31a50 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
31a60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
31a70 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
31a80 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
31a90 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31aa0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
31ab0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
31ac0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
31ad0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
31ae0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
31af0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
31b00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31b10 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
31b20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31b30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31b50 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
31b60 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
31b70 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
31b80 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
31b90 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
31ba0 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
31bb0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
31bc0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31bd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31be0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
31bf0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
31c00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
31c10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
31c20 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
31c30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31c40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31c50 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
31c60 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31c70 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
31c80 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
31c90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
31ca0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31cb0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
31cc0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
31cd0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31ce0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
31cf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31d00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31d10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31d20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
31d30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31d40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
31d60 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
31d70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
31d80 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
31d90 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
31da0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
31db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31dc0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
31dd0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
31de0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
31df0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
31e00 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
31e10 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
31e20 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
31e30 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
31e40 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
31e50 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
31e60 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
31e70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31e80 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
31e90 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
31ea0 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
31eb0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
31ec0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
31ed0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
31ee0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
31ef0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
31f00 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
31f10 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
31f20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
31f30 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
31f40 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
31f50 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
31f60 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
31f70 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
31f80 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
31f90 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
31fa0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
31fb0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
31fc0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31fd0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
31fe0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
31ff0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
32000 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
32010 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
32020 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
32030 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
32040 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
32050 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
32060 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
32070 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
32080 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
32090 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
320a0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
320b0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
320c0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
320d0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
320e0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
320f0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
32100 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
32110 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32120 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
32130 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
32140 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
32150 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
32160 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
32170 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
32180 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32190 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
321a0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
321b0 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74  r .** when first
321c0 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20   called if N is 
321d0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
321e0 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
321f0 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
32200 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
32210 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
32220 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
32230 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
32240 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32250 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
32260 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
32270 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
32280 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
32290 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
322a0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
322b0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
322c0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
322d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
322e0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
322f0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
32300 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
32310 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
32320 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
32330 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
32340 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78  )^  Within the x
32350 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20  Final callback, 
32360 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20  it is customary 
32370 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e  to set.** N=0 in
32380 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
32390 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
323a0 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74  ext(C,N) so that
323b0 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73   no .** pointles
323c0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
323d0 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a  ions occur..**.*
323e0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
323f0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
32400 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
32410 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
32420 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32430 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
32440 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
32450 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
32460 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
32470 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
32480 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
32490 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
324a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
324b0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
324c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
324d0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
324e0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
324f0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
32500 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
32510 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
32520 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
32530 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
32540 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
32550 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
32560 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
32570 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
32580 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32590 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
325a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
325b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
325c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
325d0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
325e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
325f0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
32600 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
32610 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
32620 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
32630 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
32640 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
32650 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
32660 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
32670 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
32680 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
32690 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
326a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
326b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
326c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
326d0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
326e0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
326f0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
32700 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
32710 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
32720 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
32730 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
32740 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
32750 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
32760 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32770 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
32780 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
32790 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
327a0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
327b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
327c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
327d0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
327e0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
327f0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
32800 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
32810 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
32820 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32830 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
32840 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
32850 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32860 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
32870 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
32880 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
32890 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
328a0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
328b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
328c0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
328d0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
328e0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
328f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
32900 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
32910 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
32920 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
32930 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
32940 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32950 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32960 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
32970 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
32980 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
32990 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
329a0 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20  (non-aggregate) 
329b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
329c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
329d0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
329e0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
329f0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
32a00 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
32a10 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
32a20 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
32a30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
32a40 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
32a50 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
32a60 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
32a70 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
32a80 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
32a90 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65  preserved.  An e
32aa0 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65  xample.** of whe
32ab0 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65  re this might be
32ac0 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20   useful is in a 
32ad0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
32ae0 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66  on matching.** f
32af0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
32b00 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
32b10 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
32b20 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73  ression can be s
32b30 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
32b40 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
32b50 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e  with the pattern
32b60 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68   string.  .** Th
32b70 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  en as long as th
32b80 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
32b90 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d   remains the sam
32ba0 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c  e,.** the compil
32bb0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
32bc0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
32bd0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
32be0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
32bf0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
32c00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
32c10 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32c20 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32c30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
32c40 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
32c50 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
32c60 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
32c70 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
32c80 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
32c90 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
32ca0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
32cb0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32cc0 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68  function. ^If th
32cd0 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
32ce0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
32cf0 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69   with the functi
32d00 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69  on argument, thi
32d10 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  s sqlite3_get_au
32d20 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
32d30 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  e.** returns a N
32d40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
32d50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32d60 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
32d70 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73  P,X) interface s
32d80 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61  aves P as metada
32d90 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
32da0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
32db0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32dc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
32dd0 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a    ^Subsequent.**
32de0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
32df0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
32e00 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d  N) return P from
32e10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
32e20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
32e30 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
32e40 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74   call if the met
32e50 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76  adata is still v
32e60 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20  alid or.** NULL 
32e70 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
32e80 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64  has been discard
32e90 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61  ed..** ^After ea
32ea0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
32eb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
32ec0 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20  ,N,P,X) where X 
32ed0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
32ee0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
32ef0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
32f00 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74  r function X wit
32f10 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78  h parameter P ex
32f20 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77  actly.** once, w
32f30 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61  hen the metadata
32f40 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a   is discarded..*
32f50 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
32f60 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20   to discard the 
32f70 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20  metadata at any 
32f80 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a  time, including:
32f90 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68   <ul>.** <li> wh
32fa0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
32fb0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
32fc0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c  rameter changes,
32fd0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
32fe0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32ff0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
33000 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
33010 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
33020 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
33030 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  nt, or.** <li> w
33040 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  hen sqlite3_set_
33050 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76  auxdata() is inv
33060 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  oked again on th
33070 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
33080 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72  , or.** <li> dur
33090 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
330a0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
330b0 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e  data() call when
330c0 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20   a memory .**   
330d0 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72     allocation er
330e0 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c  ror occurs. </ul
330f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
33100 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69  he last bullet i
33110 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54  n particular.  T
33120 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20  he destructor X 
33130 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  in .** sqlite3_s
33140 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
33150 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  ,X) might be cal
33160 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  led immediately,
33170 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73   before the.** s
33180 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33190 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  ta() interface e
331a0 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65  ven returns.  He
331b0 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nce sqlite3_set_
331c0 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f  auxdata().** sho
331d0 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65  uld be called ne
331e0 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  ar the end of th
331f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
33200 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68  mentation and th
33210 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d  e.** function im
33220 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
33230 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79  uld not make any
33240 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a   use of P after.
33250 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
33260 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65  uxdata() has bee
33270 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n called..**.** 
33280 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
33290 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
332a0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
332b0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
332c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
332d0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
332e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
332f0 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  stants, includin
33300 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  g literal.** val
33310 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
33320 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73  ers] and express
33330 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72  ions composed fr
33340 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a  om the same.)^.*
33350 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33360 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
33370 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
33380 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
33390 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
333a0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
333b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
333c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
333d0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
333e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
333f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
33400 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
33410 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
33420 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
33430 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
33440 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
33450 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
33460 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
33470 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
33480 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
33490 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
334a0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
334b0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
334c0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
334d0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
334e0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
334f0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
33500 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
33510 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
33520 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
33530 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
33540 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
33550 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
33560 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
33570 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
33580 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
33590 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
335a0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
335b0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
335c0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
335d0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
335e0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
335f0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
33600 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
33610 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
33620 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
33630 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
33640 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
33650 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
33660 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
33670 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
33680 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
33690 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
336a0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
336b0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
336c0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
336d0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
336e0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
336f0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
33700 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
33710 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
33720 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
33730 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
33740 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33750 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
33760 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
33770 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
33780 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
33790 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
337a0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
337b0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
337c0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
337d0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
337e0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
337f0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
33800 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
33810 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33820 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
33830 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33840 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
33850 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33860 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
33870 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
33880 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
33890 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
338a0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
338b0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
338c0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
338d0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
338e0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
338f0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
33900 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
33910 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
33920 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
33930 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33940 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
33950 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33960 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
33970 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
33980 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
33990 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
339a0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
339b0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
339c0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
339d0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
339e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
339f0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
33a00 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
33a10 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
33a20 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
33a30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33a40 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
33a50 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
33a60 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
33a70 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
33a80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33a90 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
33aa0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
33ab0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
33ac0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
33ad0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
33ae0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
33af0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
33b00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33b10 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
33b20 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
33b30 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
33b40 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
33b50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33b60 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
33b70 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
33b80 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
33b90 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
33ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33bb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33bc0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
33bd0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33be0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
33bf0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
33c00 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
33c10 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
33c20 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
33c30 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
33c40 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
33c50 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
33c60 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
33c70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33c80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
33c90 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
33ca0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
33cb0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
33cc0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
33cd0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
33ce0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
33cf0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
33d00 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
33d10 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
33d20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
33d30 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
33d40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33d50 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
33d60 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
33d70 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
33d80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
33d90 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
33da0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
33db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33dc0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
33dd0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
33de0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
33df0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
33e00 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
33e10 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
33e20 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
33e30 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
33e40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33e50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33e60 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
33e70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33e80 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
33e90 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
33ea0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
33eb0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
33ec0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
33ed0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
33ee0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
33ef0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
33f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33f10 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
33f20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33f30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
33f40 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
33f50 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
33f60 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
33f70 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
33f80 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
33f90 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
33fa0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
33fb0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
33fc0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
33fd0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
33fe0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
33ff0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34000 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
34010 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
34020 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
34030 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
34040 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
34050 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
34060 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
34070 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
34080 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
34090 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
340a0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
340b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
340c0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
340d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
340e0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
340f0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
34100 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
34110 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34120 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
34130 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
34140 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
34150 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
34160 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34170 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
34180 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
34190 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
341a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
341b0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
341c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
341d0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
341e0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
341f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34200 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
34210 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
34220 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34230 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
34240 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34250 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
34260 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34270 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34280 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
34290 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
342a0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
342b0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
342c0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
342d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
342e0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
342f0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
34300 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
34310 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34320 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34330 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
34340 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
34350 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
34360 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
34370 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34380 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
34390 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
343a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
343b0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
343c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
343d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
343e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
343f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34400 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
34410 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
34420 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34430 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
34440 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34450 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
34460 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
34470 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34480 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34490 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
344a0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
344b0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
344c0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
344d0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
344e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
344f0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
34500 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
34510 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
34520 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
34530 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
34540 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
34550 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
34560 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
34570 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
34580 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
34590 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
345a0 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
345b0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
345c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
345d0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
345e0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
345f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
34600 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
34610 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
34620 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
34630 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34640 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34650 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
34660 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
34670 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34680 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34690 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
346a0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
346b0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
346c0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
346d0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
346e0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
346f0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
34700 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
34710 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
34720 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
34730 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
34740 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
34750 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
34760 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
34770 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
34780 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
34790 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
347a0 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
347b0 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
347c0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
347d0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
347e0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
347f0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
34800 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
34810 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
34820 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
34830 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
34840 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
34850 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
34860 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
34870 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
34880 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
34890 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
348a0 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
348b0 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
348c0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
348d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
348e0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
348f0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34900 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34910 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
34920 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34930 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
34940 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34950 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
34960 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
34970 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
34980 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
34990 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
349a0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
349b0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
349c0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
349d0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
349e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
349f0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34a00 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
34a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34a20 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
34a30 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
34a40 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
34a50 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
34a60 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
34a70 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
34a80 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
34a90 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
34aa0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
34ab0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
34ac0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
34ad0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
34ae0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
34af0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
34b00 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
34b10 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
34b20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
34b30 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34b40 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34b50 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
34b60 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34b70 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34b80 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
34b90 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
34ba0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
34bb0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
34bc0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
34bd0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
34be0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
34bf0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
34c00 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
34c10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34c20 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
34c30 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
34c40 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
34c50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34c60 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34c70 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
34c80 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34c90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34ca0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
34cb0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34cc0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
34cd0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34ce0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
34cf0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34d00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
34d10 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
34d20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
34d30 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
34d40 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
34d50 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
34d60 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
34d70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34d80 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
34d90 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
34da0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
34db0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34dc0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
34dd0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
34de0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
34df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34e00 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
34e10 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
34e20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
34e30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
34e40 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
34e50 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
34e60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
34e70 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
34e80 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
34e90 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
34ea0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
34eb0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
34ec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34ed0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34ee0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
34ef0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
34f00 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
34f10 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
34f20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
34f30 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34f40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34f50 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
34f60 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
34f70 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
34f80 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
34f90 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34fa0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
34fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
34fc0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41  ouble);.SQLITE_A
34fd0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
34fe0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
34ff0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35000 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
35010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35020 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35030 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
35040 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35050 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51   void*, int);.SQ
35060 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35070 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35080 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
35090 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
350a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
350b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
350c0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
350d0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
350e0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
350f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35100 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
35110 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  text*, int);.SQL
35120 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35130 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
35140 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35150 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
35160 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
35170 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
35180 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
35190 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
351a0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
351b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
351c0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
351d0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
351e0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
351f0 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
35200 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35210 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
35220 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
35230 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35240 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35250 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
35260 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
35270 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
35280 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
35290 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
352a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
352b0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
352c0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
352d0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
352e0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
352f0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35300 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
35310 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35320 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35330 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
35340 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35360 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
35370 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
35380 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
35390 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
353a0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
353b0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
353c0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
353d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
353e0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
353f0 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
35400 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
35410 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
35420 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
35430 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
35440 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
35450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35460 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
35470 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35480 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
35490 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
354a0 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
354b0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
354c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
354d0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
354e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
354f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
35500 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
35510 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
35520 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
35530 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35540 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
35550 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
35560 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
35570 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
35580 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
35590 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
355a0 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
355b0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
355c0 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
355d0 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
355e0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
355f0 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
35600 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
35610 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
35620 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35630 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
35640 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35650 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
35660 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
35670 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35680 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
35690 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
356a0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
356b0 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
356c0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
356d0 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
356e0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
356f0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35700 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
35710 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
35720 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
35730 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
35740 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
35750 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
35760 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
35770 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
35780 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
35790 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
357a0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
357b0 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
357c0 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
357d0 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
357e0 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
357f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
35800 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
35810 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
35820 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
35830 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
35840 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
35850 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
35860 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
35870 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
35880 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
35890 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
358a0 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
358b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
358c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
358d0 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
358e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
358f0 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
35900 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
35910 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
35920 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
35930 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
35940 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
35950 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
35960 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
35970 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
35980 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
35990 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
359a0 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
359b0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
359c0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
359d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
359e0 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
359f0 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
35a00 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
35a10 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
35a20 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
35a30 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
35a40 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
35a50 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
35a60 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35a70 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
35a80 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
35a90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
35aa0 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
35ab0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
35ac0 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
35ad0 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
35ae0 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
35af0 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
35b00 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
35b10 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35b20 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
35b30 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
35b40 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
35b50 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
35b60 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
35b70 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
35b80 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
35b90 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
35ba0 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
35bb0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
35bc0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35bd0 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
35be0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
35bf0 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
35c00 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
35c10 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
35c20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35c30 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
35c40 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
35c50 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
35c60 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
35c70 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
35c80 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
35c90 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
35ca0 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
35cb0 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
35cc0 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
35cd0 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
35ce0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
35cf0 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
35d00 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
35d10 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
35d20 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
35d30 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
35d40 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
35d50 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
35d60 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
35d70 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
35d80 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
35d90 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
35da0 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
35db0 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
35dc0 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
35dd0 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
35de0 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
35df0 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
35e00 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
35e10 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
35e20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
35e30 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
35e40 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
35e50 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
35e60 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
35e70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
35e80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35e90 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
35ea0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
35eb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
35ec0 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
35ed0 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
35ee0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
35ef0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
35f00 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
35f10 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35f20 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
35f30 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
35f40 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
35f50 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
35f60 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
35f70 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
35f80 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
35f90 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
35fa0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
35fb0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
35fc0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
35fd0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
35fe0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
35ff0 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
36000 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
36010 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
36020 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
36030 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36040 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
36050 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
36060 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
36070 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
36080 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36090 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
360a0 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
360b0 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
360c0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
360d0 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
360e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
360f0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
36100 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
36110 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
36120 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
36130 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
36140 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
36150 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
36160 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
36170 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
36180 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
36190 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
361a0 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
361b0 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
361c0 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
361d0 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
361e0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
361f0 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
36200 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36210 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
36220 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36230 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ed16()]..*/.SQLI
36240 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36250 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36260 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
36270 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
36280 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
36290 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
362a0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
362b0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
362c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
362d0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
362e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
362f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36300 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
36310 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
36320 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
36330 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36340 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
36350 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
36360 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
36370 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
36380 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
36390 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
363a0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
363b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
363c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
363d0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
363e0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
363f0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
36400 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
36410 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
36420 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
36430 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
36440 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
36450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
36460 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
36470 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
36480 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
36490 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
364a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
364b0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
364c0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
364d0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
364e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
364f0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
36500 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
36510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36520 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
36530 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
36540 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
36550 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
36560 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
36570 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
36580 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
36590 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
365a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
365b0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
365c0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
365d0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
365e0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
365f0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
36600 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
36610 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
36620 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
36630 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
36640 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
36650 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
36660 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
36670 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36680 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
36690 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
366a0 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
366b0 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
366c0 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
366d0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
366e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
366f0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
36700 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
36710 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
36720 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
36730 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
36740 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36750 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
36760 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36770 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
36780 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
36790 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
367a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
367b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
367c0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
367d0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
367e0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
367f0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
36800 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
36810 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
36820 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
36830 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
36840 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
36850 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
36860 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
36870 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
36880 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
36890 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
368a0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
368b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
368c0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
368d0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
368e0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
368f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36900 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
36910 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36920 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
36930 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36940 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
36950 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36960 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
36970 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
36980 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
36990 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
369a0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
369b0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
369c0 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54   char*).);.SQLIT
369d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
369e0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
369f0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
36a00 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
36a10 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
36a20 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
36a30 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
36a40 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
36a50 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
36a60 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
36a70 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
36a80 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
36a90 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
36aa0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
36ab0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
36ac0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
36ad0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
36ae0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
36af0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
36b00 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
36b10 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
36b20 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
36b30 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  I int sqlite3_ke
36b40 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
36b50 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36b60 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
36b70 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
36b80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
36b90 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
36ba0 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
36bb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
36bc0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32  t sqlite3_key_v2
36bd0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36bf0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
36c00 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
36c10 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
36c20 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
36c30 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
36c40 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
36c50 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36c60 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36c70 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
36c80 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
36c90 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
36ca0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
36cb0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
36cc0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
36cd0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
36ce0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
36cf0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
36d00 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
36d10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
36d20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
36d30 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
36d40 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36d50 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
36d60 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
36d70 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
36d80 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
36d90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
36da0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
36db0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36dc0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
36dd0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
36de0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
36df0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
36e00 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
36e10 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  key */.);.SQLITE
36e20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36e30 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c  _rekey_v2(.  sql
36e40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36e50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
36e60 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
36e70 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
36e80 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
36e90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d            /* Nam
36ea0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
36eb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
36ec0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
36ed0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
36ee0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
36ef0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
36f00 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
36f10 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
36f20 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
36f30 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
36f40 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
36f50 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53   will work..*/.S
36f60 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
36f70 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
36f80 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
36f90 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
36fa0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
36fb0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
36fc0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
36fd0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
36fe0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
36ff0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
37000 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
37010 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
37020 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
37030 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
37040 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
37050 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
37060 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37070 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
37080 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
37090 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
370a0 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
370b0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
370c0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
370d0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
370e0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
370f0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
37100 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
37110 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
37120 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
37130 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
37140 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
37150 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
37160 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
37170 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
37180 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
37190 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
371a0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
371b0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
371c0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
371d0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
371e0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
371f0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
37200 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
37210 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
37220 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
37230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
37240 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
37250 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
37260 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
37270 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
37280 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
37290 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
372a0 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
372b0 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
372c0 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
372d0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
372e0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
372f0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
37300 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
37310 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
37320 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
37330 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
37340 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
37350 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
37360 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
37370 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
37380 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
37390 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
373a0 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
373b0 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
373c0 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
373d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
373e0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
373f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37400 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
37410 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
37420 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
37430 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
37440 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
37450 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
37460 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
37470 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
37480 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
37490 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
374a0 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
374b0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
374c0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
374d0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
374e0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
374f0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
37500 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
37510 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
37520 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
37530 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
37540 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37550 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
37560 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
37570 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
37580 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
37590 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
375a0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
375b0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
375c0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
375d0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
375e0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
375f0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
37600 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
37610 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37620 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
37630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37640 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
37650 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
37660 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
37670 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
37680 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
37690 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
376a0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
376b0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
376c0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
376d0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
376e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
376f0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
37700 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
37710 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
37720 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
37730 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
37740 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
37750 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
37760 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
37770 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
37780 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
37790 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
377a0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
377b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
377c0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
377d0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
377e0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
377f0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
37800 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
37810 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
37820 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
37830 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
37840 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
37850 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
37860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
37870 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
37880 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
37890 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
378a0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
378b0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
378c0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
378d0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
378e0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
378f0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
37900 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
37910 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
37920 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
37930 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
37940 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
37950 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
37960 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
37970 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
37980 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
37990 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
379a0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
379b0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
379c0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
379d0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
379e0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
379f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
37a00 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  n] or [sqlite3_o
37a10 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77  pen_v2].  Otherw
37a20 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
37a30 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
37a40 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
37a50 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
37a60 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65   may fail.  Here
37a70 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c   is an.** exampl
37a80 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74  e of how to do t
37a90 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69  his using C++ wi
37aa0 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52  th the Windows R
37ab0 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62  untime:.**.** <b
37ac0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
37ad0 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68  ** LPCWSTR zPath
37ae0 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72   = Windows::Stor
37af0 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e  age::Application
37b00 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a  Data::Current->.
37b10 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65  ** &nbsp;     Te
37b20 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50  mporaryFolder->P
37b30 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20  ath->Data();.** 
37b40 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39  char zPathBuf&#9
37b50 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23  1;MAX_PATH + 1&#
37b60 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a  93;;.** memset(z
37b70 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65  PathBuf, 0, size
37b80 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a  of(zPathBuf));.*
37b90 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74  * WideCharToMult
37ba0 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30  iByte(CP_UTF8, 0
37bb0 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61  , zPath, -1, zPa
37bc0 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50  thBuf, sizeof(zP
37bd0 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73  athBuf),.** &nbs
37be0 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c  p;     NULL, NUL
37bf0 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  L);.** sqlite3_t
37c00 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20  emp_directory = 
37c10 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
37c20 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b  "%s", zPathBuf);
37c30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
37c40 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54  kquote>.*/.SQLIT
37c50 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54  E_API SQLITE_EXT
37c60 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
37c70 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
37c80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37c90 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
37ca0 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61  older Holding Da
37cb0 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a  tabase Files.**.
37cc0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
37cd0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
37ce0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
37cf0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
37d00 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
37d10 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
37d20 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
37d30 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65  hen all database
37d40 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66   files.** specif
37d50 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61 74  ied with a relat
37d60 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64  ive pathname and
37d70 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63 65   created or acce
37d80 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ssed by.** SQLit
37d90 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
37da0 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20  uilt-in windows 
37db0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
37dc0 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75  FS] will be assu
37dd0 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c  med.** to be rel
37de0 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64 69  ative to that di
37df0 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74  rectory.)^ ^If t
37e00 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
37e10 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
37e20 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  r, then SQLite a
37e30 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20  ssumes that all 
37e40 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 73  database files s
37e50 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68  pecified.** with
37e60 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
37e70 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76  name are relativ
37e80 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  e to the current
37e90 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f   directory.** fo
37ea0 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20  r the process.  
37eb0 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73  Only the windows
37ec0 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f   VFS makes use o
37ed0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a  f this global.**
37ee0 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73   variable; it is
37ef0 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20   ignored by the 
37f00 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  unix VFS..**.** 
37f10 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c  Changing the val
37f20 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69 61  ue of this varia
37f30 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74 61  ble while a data
37f40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37f50 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72  is.** open can r
37f60 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75  esult in a corru
37f70 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a  pt database..**.
37f80 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
37f90 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
37fa0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
37fb0 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
37fc0 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
37fd0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
37fe0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
37ff0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
38000 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
38010 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38020 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
38030 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
38040 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
38050 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
38060 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
38070 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
38080 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
38090 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
380a0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
380b0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
380c0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
380d0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
380e0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
380f0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
38100 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
38110 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
38120 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
38130 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64  he [data_store_d
38140 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
38150 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
38160 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
38170 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
38180 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
38190 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
381a0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
381b0 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
381c0 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64  he [data_store_d
381d0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
381e0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
381f0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
38200 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
38210 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
38220 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
38230 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
38240 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
38250 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
38260 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
38270 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
38280 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
38290 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
382a0 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
382b0 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
382c0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
382d0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
382e0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
382f0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
38300 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
38310 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
38320 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
38330 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
38340 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64  he [data_store_d
38350 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
38360 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
38370 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
38380 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
38390 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61  char *sqlite3_da
383a0 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  ta_directory;../
383b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
383c0 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
383d0 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
383e0 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
383f0 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
38400 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
38410 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
38420 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
38430 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
38440 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
38450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38460 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
38470 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
38480 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
38490 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
384a0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
384b0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
384c0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
384d0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
384e0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
384f0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
38500 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
38510 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
38520 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
38530 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
38540 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
38550 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
38560 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
38570 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
38580 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
38590 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
385a0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
385b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
385c0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
385d0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
385e0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
385f0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
38600 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
38610 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
38620 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
38630 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
38640 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
38650 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
38660 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
38670 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
38680 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
38690 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
386a0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
386b0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
386c0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
386d0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
386e0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
386f0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
38700 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
38710 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
38720 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
38730 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
38740 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
38750 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
38760 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
38770 74 6f 63 6f 6d 6d 69 74 28 73 71 6c