System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact db931a0a595122bcb8924962d9b66186f5beb823:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 31 35 22 0a 23 64 65 66 69 6e 65 20 53  .7.15".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 35 0a 23 64 65  MBER 3007015.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 31 32 2d 31 32 20 31 33 3a 33 36 3a 35 33 20  -12-12 13:36:53 
1080: 63 64 30 62 33 37 63 35 32 36 35 38 62 66 64 66  cd0b37c52658bfdf
1090: 39 39 32 62 31 65 33 64 63 34 36 37 62 61 65 31  992b1e3dc467bae1
10a0: 38 33 35 61 39 34 61 65 22 0a 0a 2f 2a 0a 2a 2a  835a94ae"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  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 2f 2a                /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 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 2f 2a                /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **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 2f 2a 20 45 72 72            /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
55f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5600: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5610: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5630: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5640: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5650: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5670: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5690: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
56a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
56b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
56c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
56d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56f0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5700: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5710: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5720: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5730: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5740: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5750: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5760: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5770: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5780: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57b0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
57c0: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
57d0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5800: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5810: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5820: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5830: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5840: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5850: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5860: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5870: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5880: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5890: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
58a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
58b0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
58c0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
58d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
58e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
58f0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5910: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5920: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5930: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5940: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5960: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5970: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5980: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5990: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
59a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
59c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59d0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
59e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
59f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a00: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5a10: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5a20: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5a30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a40: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5a50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a60: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a80: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5a90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5aa0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ac0: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ae0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5af0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5b00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b10: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5b20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b30: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5b40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5bb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5be0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5bf0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c20: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5c30: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5c40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c60: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5c70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5c80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ca0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5cb0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
5cc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ce0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5cf0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
5d00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5d10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d20: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5d30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5d40: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d70: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5d80: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5d90: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5da0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5dd0: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5de0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5df0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e10: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5e20: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5e30: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5e40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e60: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5e70: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5e80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5e90: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5ea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5ec0: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5ed0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5ee0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5ef0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5f00: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5f10: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5f20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5f30: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5f40: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5f50: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5f60: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5f70: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5f80: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5f90: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5fa0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5fb0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5fc0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5fd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5fe0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5ff0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6000: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6010: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6020: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6030: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6040: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6050: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6060: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6070: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6080: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6090: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
60a0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
60b0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
60c0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
60d0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
60e0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
60f0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6100: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6110: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6120: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6130: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6140: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6150: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6160: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6170: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6180: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6190: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
61a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
61b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
61c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
61d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
61e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
61f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6200: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6210: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6220: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6230: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6240: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6250: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6260: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6270: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6280: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6290: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
62a0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
62b0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
62c0: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
62d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
62e0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
62f0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6300: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6310: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6320: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6330: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6340: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6350: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
6360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6370: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6390: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
63a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
63b0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
63c0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
63d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
63e0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
63f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6410: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6430: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6450: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6460: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6480: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64a0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
64b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
64c0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
64d0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
64e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
64f0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6510: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6520: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6530: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6540: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6550: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6560: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6570: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6580: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6590: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
65a0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
65b0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
65c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
65d0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
65e0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
65f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6600: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6610: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6620: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6630: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6640: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6650: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6660: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6670: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6680: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6690: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
66a0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
66b0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
66c0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
66d0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
66e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
66f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6700: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6710: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6720: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6730: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6740: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6750: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6770: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6780: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6790: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
67a0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
67b0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
67c0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
67d0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
67e0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
67f0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6800: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6810: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6820: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6830: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6840: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6850: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6860: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6870: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6880: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6890: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
68a0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
68b0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
68c0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
68d0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
68e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
68f0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6900: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6910: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6920: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6930: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6940: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6950: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6960: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6970: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6980: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6990: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
69a0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
69b0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
69c0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
69d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
69e0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
69f0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6a00: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6a10: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6a20: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6a30: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6a40: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6a50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6a60: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6a70: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6a80: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6a90: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
6aa0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
6ab0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6ac0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6ad0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6ae0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6af0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6b00: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6b10: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6b20: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6b30: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6b40: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6b50: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6b60: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6b70: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6b80: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6b90: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6ba0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6bb0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6bc0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6bd0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6be0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6bf0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6c00: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6c10: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6c20: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6c30: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6c40: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6c50: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6c60: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6c70: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6c80: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6c90: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6ca0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6cb0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6cd0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6ce0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6cf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6d00: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6d10: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6d20: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6d30: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6d40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6d50: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6d60: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6d70: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6d80: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6d90: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6da0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6db0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6dc0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6dd0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6de0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6df0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6e00: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6e10: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6e20: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6e30: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6e40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6e50: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6e60: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6e70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6e80: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6e90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6ea0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6eb0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6ec0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6ed0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6ee0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6ef0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6f00: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6f10: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6f20: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6f30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6f40: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6f50: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6f60: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6f70: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6f80: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6f90: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6fa0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6fb0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6fc0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6fd0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6fe0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6ff0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7000: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7010: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7020: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7030: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7040: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7050: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7060: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7070: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
7080: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7090: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
70a0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
70b0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
70c0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
70d0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
70e0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
70f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7100: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7110: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7120: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7130: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7140: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7150: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7160: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7170: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7180: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7190: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
71a0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
71b0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
71c0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
71d0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
71e0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
71f0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7200: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7210: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7220: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7230: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7240: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7250: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7260: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7270: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7280: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7290: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
72a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
72b0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
72c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
72d0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
72e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
72f0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7300: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7310: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7320: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7330: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7340: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7350: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7360: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7370: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7380: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7390: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
73a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
73b0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
73c0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
73d0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
73e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
73f0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7400: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7410: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7420: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7430: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7440: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7450: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7460: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7470: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7480: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7490: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
74a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
74b0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
74c0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
74d0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
74e0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
74f0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7500: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7510: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7520: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7530: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7540: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7550: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7560: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7570: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7580: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7590: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
75a0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
75b0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
75c0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
75d0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
75e0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
75f0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7600: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7610: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7620: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7630: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7640: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7650: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7660: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7670: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7680: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7690: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
76a0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
76b0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
76c0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
76d0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
76e0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
76f0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7700: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7710: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7720: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7730: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7740: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7750: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7760: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7770: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7780: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7790: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
77a0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
77b0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
77c0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
77d0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
77e0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
77f0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7800: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7810: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7820: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7830: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7840: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7850: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7860: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7870: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7880: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7890: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
78a0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
78b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
78c0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
78d0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
78e0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
78f0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7900: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7910: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7920: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7930: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7940: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7950: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7960: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7970: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7980: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7990: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
79a0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
79b0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
79c0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
79d0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
79e0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
79f0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7a00: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7a10: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7a20: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7a30: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7a40: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7a50: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7a60: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7a70: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7a80: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7a90: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
7aa0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7ab0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7ac0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7ad0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7ae0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7af0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7b00: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7b10: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7b20: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7b30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b40: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7b50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7b60: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7b70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b80: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7b90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ba0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7bb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7bc0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7bd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7be0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7bf0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7c00: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7c10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7c20: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7c30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7c40: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7c60: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7c70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7c80: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7c90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7cb0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7cc0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7cd0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7ce0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7cf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7d00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7d10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7d20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7d30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7d40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7d50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7d60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7d70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7d80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7d90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7da0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7db0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7dc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7dd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7de0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7df0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7e00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7e10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7e20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7e30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7e40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7e50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7e60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7e70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7e80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7e90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7ea0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7eb0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7ec0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7ed0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7ee0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7ef0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7f00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7f10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7f20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7f30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7f40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7f50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7f60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7f70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7f80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7f90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7fa0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7fb0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7fc0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7fd0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7fe0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7ff0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8000: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8010: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8020: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8030: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8040: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8050: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8060: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8070: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
8080: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8090: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
80a0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
80b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
80c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
80d0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
80e0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
80f0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8100: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8110: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8120: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8130: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8140: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8150: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8160: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8170: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8180: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8190: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
81a0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
81b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
81c0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
81d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
81e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
81f0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8200: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8210: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8220: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8230: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8240: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8250: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
8260: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
8270: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8280: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8290: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
82a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
82b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
82c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
82d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
82e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
82f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8300: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8310: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8320: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8330: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8340: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8350: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
8360: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
8370: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
8380: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8390: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
83a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
83b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
83c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
83d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
83e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
83f0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8400: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8410: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8420: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8430: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8440: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8450: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
8460: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8470: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8480: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8490: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
84a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
84b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
84c0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
84d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
84e0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
84f0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8500: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8510: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8520: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8530: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8540: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8550: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8560: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8570: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8580: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8590: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
85a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
85b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
85c0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
85d0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
85e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
85f0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8600: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8610: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8620: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8630: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8640: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8650: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8660: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8670: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
8680: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
8690: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
86a0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
86b0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
86c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
86d0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
86e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
86f0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8700: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8710: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8720: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8730: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8740: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8750: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8760: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8770: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8780: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8790: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
87a0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
87b0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
87c0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
87d0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
87e0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
87f0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8800: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8810: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8820: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8830: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8840: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8850: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8860: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8870: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8880: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8890: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
88a0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
88b0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
88c0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
88d0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
88e0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
88f0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8900: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8910: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8920: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8930: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8940: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8950: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
8960: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8970: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8980: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8990: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
89a0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
89b0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
89c0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
89d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
89e0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
89f0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8a00: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8a10: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8a20: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8a30: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8a40: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8a50: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
8a60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8a70: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8a80: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
8a90: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
8aa0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
8ab0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8ac0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8ad0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8ae0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8af0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8b00: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8b10: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8b20: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8b30: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8b40: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8b50: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8b60: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8b70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8b80: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8b90: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8ba0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8bb0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8bc0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8bd0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8be0: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8bf0: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8c00: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8c10: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8c20: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8c30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8c40: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8c50: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8c60: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8c70: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8c80: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8c90: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8ca0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8cb0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8cc0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8cd0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8ce0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8cf0: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8d00: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8d10: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8d20: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8d30: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8d40: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8d50: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8d60: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8d70: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8d80: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8d90: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8da0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8db0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8dc0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8dd0: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8de0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8df0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e00: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8e10: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8e20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8e30: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8e50: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8e60: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8e70: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8e80: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8e90: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8ea0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8eb0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8ec0: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8ed0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8ee0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8ef0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8f00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8f10: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8f20: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8f30: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8f40: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8f50: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8f60: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8f70: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8f80: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8f90: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8fa0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8fb0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8fc0: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8fd0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8fe0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8ff0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
9000: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
9010: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
9020: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9030: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9040: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9050: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9060: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9070: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9080: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9090: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
90a0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
90b0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
90c0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
90d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
90e0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
90f0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9100: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9110: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9120: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9130: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9140: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9150: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9160: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9170: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9180: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9190: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
91a0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
91b0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
91c0: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
91d0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
91e0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
91f0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9200: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9210: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9220: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9230: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9240: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9250: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9260: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9270: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9280: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9290: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
92a0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
92b0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
92c0: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
92d0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
92e0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
92f0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9300: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9310: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9320: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9330: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9340: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9350: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9360: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9370: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9380: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9390: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
93a0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
93b0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
93c0: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
93d0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
93e0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
93f0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9400: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9410: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9420: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9430: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9440: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9450: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9460: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
9470: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
9480: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
9490: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
94a0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
94b0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
94c0: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
94d0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
94e0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
94f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9500: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9510: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9520: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9530: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9540: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9550: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9560: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
9570: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
9580: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
9590: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
95a0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
95b0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
95c0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
95d0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
95e0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
95f0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9600: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9610: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9620: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9630: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9640: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9650: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9660: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9670: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9680: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
9690: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
96a0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
96b0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
96c0: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
96d0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
96e0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
96f0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9700: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9710: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9720: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9730: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9740: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9750: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9760: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9770: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9780: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9790: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
97a0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
97b0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
97c0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
97d0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
97e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
97f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9800: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9810: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9820: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9830: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9840: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9850: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9860: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
9870: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9880: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9890: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
98a0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
98b0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
98c0: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
98d0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
98e0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
98f0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9900: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9910: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9920: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9930: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9940: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9950: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
9960: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
9970: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
9980: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
9990: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
99b0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
99c0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
99d0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
99e0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
99f0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9a00: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9a10: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9a20: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9a30: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9a40: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9a50: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
9a60: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
9a70: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
9a80: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
9a90: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
9aa0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
9ab0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9ac0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9ad0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9ae0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9af0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9b00: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9b10: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9b20: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9b30: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9b40: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9b50: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9b60: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9b70: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9b80: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9b90: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9ba0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9bb0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9bc0: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9bd0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9be0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9bf0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9c00: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9c10: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9c20: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9c30: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9c40: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9c50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9c60: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9c70: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9c80: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9c90: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9ca0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9cb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9cc0: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9cd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9ce0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9cf0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9d00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9d10: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9d20: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9d30: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9d40: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9d50: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9d60: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9d70: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9d80: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9d90: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9da0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9db0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9dc0: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9dd0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9de0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9df0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9e00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9e10: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9e20: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9e30: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9e40: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9e50: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9e60: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9e70: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9e80: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9e90: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9ea0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9eb0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9ec0: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9ed0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9ee0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9ef0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9f00: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9f10: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9f20: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9f30: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9f40: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9f50: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9f60: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9f70: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9f80: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9f90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9fa0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9fb0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9fc0: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9fd0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9fe0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9ff0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
a000: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a010: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a020: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
a030: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
a040: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
a050: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
a060: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
a070: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
a080: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
a090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
a0a0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a0b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a0c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a0d0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
a0e0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
a0f0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a100: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a110: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a120: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a130: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a140: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a150: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a160: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a170: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a180: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a190: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a1a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a1b0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a1c0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a1d0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a1e0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a1f0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a200: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a210: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a220: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a230: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
a240: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a250: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
a260: 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 2d  ].** ^This file-
a270: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
a280: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a290: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
a2a0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
a2b0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
a2c0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
a2d0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
a2e0: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
a2f0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
a300: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
a310: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
a320: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
a330: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
a340: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
a350: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
a360: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
a370: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
a380: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
a390: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
a3a0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
a3b0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
a3c0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
a3d0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
a3e0: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
a3f0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
a400: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
a410: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
a420: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
a430: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
a440: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
a450: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
a460: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
a470: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
a480: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
a490: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
a4a0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
a4b0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
a4c0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
a4d0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
a4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a4f0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
a500: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
a510: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
a520: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a530: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
a540: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
a550: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
a560: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
a570: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
a580: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
a590: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
a5a0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
a5b0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
a5c0: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
a5d0: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
a5e0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
a5f0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
a600: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
a610: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
a620: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
a630: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a640: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a650: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
a660: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
a670: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
a680: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
a690: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
a6a0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
a6b0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
a6c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a6d0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
a6e0: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
a6f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
a700: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
a710: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
a720: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
a730: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
a740: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
a750: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
a760: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
a770: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
a780: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
a790: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
a7a0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
a7b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
a7c0: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
a7d0: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
a7f0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
a800: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
a810: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
a820: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
a830: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
a840: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
a850: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
a860: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
a870: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a880: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
a890: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
a8a0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a8b0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
a8c0: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
a8d0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
a8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
a8f0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
a900: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a910: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
a920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a930: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
a940: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
a950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a960: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a970: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
a980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a990: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
a9a0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 0a 2f             16../
a9b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
a9c0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
a9d0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
a9e0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
a9f0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
aa00: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
aa10: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
aa20: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
aa30: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
aa40: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
aa50: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
aa60: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
aa70: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
aa80: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
aa90: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
aaa0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
aab0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
aac0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
aad0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
aae0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
aaf0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
ab00: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
ab10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
ab20: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
ab30: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
ab40: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
ab50: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
ab60: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ab70: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
ab80: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
ab90: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
aba0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
abb0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
abc0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
abd0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
abe0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
abf0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
ac00: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
ac10: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
ac20: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
ac30: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
ac40: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
ac50: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
ac60: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
ac70: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
ac80: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
ac90: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
aca0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
acb0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
acc0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
acd0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
ace0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
acf0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
ad00: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
ad10: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
ad20: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
ad30: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
ad40: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
ad50: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
ad60: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
ad70: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
ad80: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
ad90: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
ada0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
adb0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
adc0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
add0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
ade0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
adf0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
ae00: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
ae10: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
ae20: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
ae30: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
ae40: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
ae50: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
ae60: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
ae70: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
ae80: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
ae90: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
aea0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
aeb0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
aec0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
aed0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
aee0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
aef0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
af00: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
af10: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
af20: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
af30: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
af40: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
af50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
af60: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
af70: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
af80: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
af90: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
afa0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
afb0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
afc0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
afd0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
afe0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
aff0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
b000: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
b010: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
b020: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
b030: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
b040: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
b050: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
b060: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
b070: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
b080: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
b090: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
b0a0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
b0b0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
b0c0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
b0d0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
b0e0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
b0f0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
b100: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
b110: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
b120: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
b130: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
b140: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
b150: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
b160: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
b170: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
b180: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b190: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
b1a0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
b1b0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
b1c0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
b1d0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
b1e0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
b1f0: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
b200: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
b210: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
b220: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
b230: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
b240: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
b250: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
b260: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b270: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
b280: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
b290: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
b2a0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
b2b0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
b2c0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
b2d0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
b2e0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
b2f0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
b300: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
b310: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
b320: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
b330: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
b340: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
b350: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
b360: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
b370: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
b380: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
b390: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
b3a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
b3b0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
b3c0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
b3d0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
b3e0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
b3f0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
b400: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
b410: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
b420: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
b430: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
b440: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
b450: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
b460: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
b470: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
b480: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
b490: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
b4a0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
b4b0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
b4c0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
b4d0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
b4e0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
b4f0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
b500: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b510: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
b520: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
b530: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
b540: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
b550: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
b560: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
b570: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
b580: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
b590: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
b5a0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
b5b0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
b5c0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
b5d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
b5e0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
b5f0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
b600: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
b610: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
b620: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
b630: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
b640: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
b650: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
b660: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
b670: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
b680: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
b690: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
b6a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
b6b0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
b6c0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
b6d0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
b6e0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
b6f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b700: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
b710: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b720: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
b730: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
b740: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
b750: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b760: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
b770: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
b780: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
b790: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
b7a0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b7b0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
b7c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b7d0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
b7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b7f0: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
b800: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
b810: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
b820: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
b830: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
b840: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
b850: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
b860: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
b870: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b880: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
b890: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
b8a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
b8b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
b8c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
b8d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
b8e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
b8f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
b900: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
b910: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
b920: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
b930: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
b940: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
b950: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
b960: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
b970: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
b980: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
b990: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
b9a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
b9b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
b9c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
b9d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
b9e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
b9f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
ba00: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
ba10: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
ba20: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
ba30: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
ba40: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
ba50: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
ba60: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
ba70: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
ba80: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
ba90: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
baa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
bab0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
bac0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
bad0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
bae0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
baf0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
bb00: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
bb10: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
bb20: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
bb30: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
bb40: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
bb50: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
bb60: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
bb70: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
bb80: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
bb90: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
bba0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
bbb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
bbc0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
bbd0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
bbe0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
bbf0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
bc00: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
bc10: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
bc20: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
bc30: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
bc40: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
bc50: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
bc60: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
bc70: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
bc80: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
bc90: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
bca0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
bcb0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
bcc0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
bcd0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
bce0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
bcf0: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
bd00: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
bd10: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
bd20: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
bd30: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
bd40: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
bd50: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
bd60: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
bd70: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
bd80: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
bd90: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
bda0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
bdb0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
bdc0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
bdd0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
bde0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
bdf0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
be00: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
be10: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
be20: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
be30: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
be40: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
be50: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
be60: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
be70: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
be80: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
be90: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
bea0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
beb0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
bec0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
bed0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
bee0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
bef0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
bf00: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
bf10: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
bf20: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
bf30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
bf40: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
bf50: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
bf60: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
bf70: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
bf80: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
bf90: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
bfa0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
bfb0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
bfc0: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
bfd0: 0a 2a 2a 20 5e 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 41 63 63 65  rgument to xAcce
bff0: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
c000: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
c010: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
c020: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
c030: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
c040: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
c050: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
c060: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
c070: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
c080: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
c090: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c0a0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
c0b0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
c0c0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
c0d0: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
c0e0: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
c0f0: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
c100: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
c110: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
c120: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
c130: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
c140: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
c150: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
c160: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
c170: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
c180: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
c190: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
c1a0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
c1b0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
c1c0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
c1d0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
c1e0: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
c1f0: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
c200: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
c210: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
c220: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
c230: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
c240: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c250: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
c260: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
c270: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
c280: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
c290: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
c2a0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
c2b0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
c2c0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
c2d0: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
c2e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c2f0: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
c300: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
c310: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
c320: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
c330: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
c340: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
c350: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
c360: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
c370: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
c380: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
c390: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
c3a0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
c3b0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
c3c0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
c3d0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
c3e0: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
c3f0: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
c400: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
c410: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
c420: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
c430: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
c440: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
c450: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
c460: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
c470: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
c480: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
c490: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
c4a0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
c4b0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
c4c0: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
c4d0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
c4e0: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
c4f0: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
c500: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
c510: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c520: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
c530: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
c540: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
c550: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
c560: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
c570: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
c580: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
c590: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
c5a0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
c5b0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
c5c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c5d0: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
c5e0: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
c5f0: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
c600: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
c610: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
c620: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
c630: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
c640: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
c650: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
c660: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
c670: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
c680: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
c690: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
c6a0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
c6b0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
c6c0: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
c6d0: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
c6e0: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
c6f0: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
c700: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
c710: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
c720: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
c730: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
c740: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
c750: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
c760: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
c770: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
c780: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
c790: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
c7a0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
c7b0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
c7c0: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
c7d0: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
c7e0: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
c7f0: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
c800: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
c810: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
c820: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
c830: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
c840: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
c850: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
c860: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
c870: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
c880: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
c890: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
c8a0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
c8b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
c8c0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
c8d0: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
c8e0: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
c8f0: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
c900: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
c910: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
c920: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
c930: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
c940: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
c950: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
c960: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
c970: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
c980: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
c990: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
c9a0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
c9b0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
c9c0: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
c9d0: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
c9e0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c9f0: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
ca00: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
ca10: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
ca20: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
ca30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
ca40: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
ca50: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
ca60: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
ca70: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
ca80: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
ca90: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
caa0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
cab0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
cac0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
cad0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
cae0: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
caf0: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
cb00: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
cb10: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
cb20: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
cb30: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
cb40: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
cb50: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
cb60: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
cb70: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
cb80: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
cb90: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
cba0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
cbb0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
cbc0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
cbd0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
cbe0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
cbf0: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
cc00: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
cc10: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
cc20: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
cc30: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
cc40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cc50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cc60: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
cc70: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
cc80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cc90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cca0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
ccb0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
ccc0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
ccd0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
cce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ccf0: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
cd00: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
cd10: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
cd20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cd30: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
cd40: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
cd50: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
cd60: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
cd70: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
cd80: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
cd90: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
cda0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
cdb0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
cdc0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
cdd0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
cde0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
cdf0: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
ce00: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
ce10: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
ce20: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
ce30: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
ce40: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
ce50: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
ce60: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
ce70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
ce80: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
ce90: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
cea0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
ceb0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
cec0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ced0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
cee0: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
cef0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cf00: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
cf10: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
cf20: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
cf30: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
cf40: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
cf50: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
cf60: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
cf70: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
cf80: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
cf90: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
cfa0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
cfb0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
cfc0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cfd0: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
cfe0: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
cff0: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
d000: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
d010: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
d020: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
d030: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
d040: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
d050: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
d060: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
d070: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
d080: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d090: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
d0a0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
d0b0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
d0c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d0d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d0e0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
d0f0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
d100: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
d110: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
d120: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d130: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
d140: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
d150: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
d160: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
d170: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
d180: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
d190: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
d1a0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
d1b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d1c0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d1d0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
d1e0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
d1f0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
d200: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
d210: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
d220: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
d230: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
d240: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
d250: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
d260: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
d270: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
d280: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
d290: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
d2a0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
d2b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d2c0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
d2d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
d2e0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
d2f0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
d300: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
d310: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d320: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
d330: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d340: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
d350: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
d360: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
d370: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
d380: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d390: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
d3a0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
d3b0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
d3c0: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
d3d0: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
d3e0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
d3f0: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
d400: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
d410: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
d420: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
d430: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
d440: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
d450: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
d460: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
d470: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
d480: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d490: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
d4a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d4b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
d4c0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
d4d0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
d4e0: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
d4f0: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
d500: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
d510: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
d520: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
d530: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
d540: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
d550: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d560: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
d570: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d580: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
d590: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
d5a0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
d5b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
d5c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
d5d0: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
d5e0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
d5f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
d600: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
d610: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d620: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d630: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
d640: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
d650: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
d660: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
d670: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
d680: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
d690: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
d6a0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
d6b0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
d6c0: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
d6d0: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
d6e0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
d6f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d700: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
d710: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
d720: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
d730: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
d740: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
d750: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
d760: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
d770: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
d780: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
d790: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d7a0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
d7b0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
d7c0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
d7d0: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
d7e0: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
d7f0: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
d800: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
d810: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
d820: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
d830: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
d840: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d850: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
d860: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
d870: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
d880: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
d890: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
d8a0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
d8b0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
d8c0: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
d8d0: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
d8e0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
d8f0: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
d900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
d910: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
d920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
d930: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
d940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d950: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
d960: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
d970: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
d980: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
d990: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
d9a0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
d9b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
d9c0: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
d9d0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
d9e0: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
d9f0: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
da00: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
da10: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
da20: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
da30: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
da40: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
da50: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
da60: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
da70: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
da80: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
da90: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
daa0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
dab0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
dac0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
dad0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
dae0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
daf0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
db00: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
db10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
db20: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
db30: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
db40: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
db50: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
db60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
db70: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
db80: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
db90: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
dba0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
dbb0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
dbc0: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
dbd0: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
dbe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
dbf0: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
dc00: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
dc10: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
dc20: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
dc30: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
dc40: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
dc50: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
dc60: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
dc70: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
dc80: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
dc90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dca0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
dcb0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
dcc0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
dcd0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
dce0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
dcf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dd00: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
dd10: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
dd20: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
dd30: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
dd40: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
dd50: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
dd60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dd70: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
dd80: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
dd90: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
dda0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
ddb0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
ddc0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ddd0: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
dde0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ddf0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
de00: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
de10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
de20: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
de30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
de40: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
de50: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
de60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
de70: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
de80: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
de90: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
dea0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
deb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dec0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ded0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
dee0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
def0: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
df00: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
df10: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
df20: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
df30: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
df40: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
df50: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
df60: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
df70: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
df80: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
df90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dfa0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
dfb0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
dfc0: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
dfd0: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
dfe0: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
dff0: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
e000: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
e010: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
e020: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
e030: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e040: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
e050: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e060: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
e070: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e080: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
e090: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
e0a0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
e0b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e0c0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
e0d0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
e0e0: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
e0f0: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
e100: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
e110: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
e120: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
e130: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
e140: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
e150: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
e160: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
e170: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
e180: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
e190: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
e1a0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
e1b0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
e1c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
e1d0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
e1e0: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
e1f0: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
e200: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
e210: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
e220: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
e230: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
e240: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
e250: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
e260: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
e270: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
e280: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
e290: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
e2a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e2b0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
e2c0: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
e2d0: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
e2e0: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
e2f0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
e300: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
e310: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
e320: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
e330: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
e340: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
e350: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
e360: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
e370: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
e380: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
e390: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
e3a0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
e3b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
e3c0: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
e3d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e3e0: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
e3f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e400: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
e410: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
e420: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
e430: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
e440: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
e450: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
e460: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
e470: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
e480: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e490: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
e4a0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
e4b0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e4c0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e4d0: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
e4e0: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
e4f0: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
e500: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
e510: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
e520: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
e530: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
e540: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
e550: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
e560: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
e570: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
e580: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
e590: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
e5a0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
e5b0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
e5c0: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
e5d0: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
e5e0: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
e5f0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
e600: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
e610: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
e620: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
e630: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
e640: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
e650: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
e660: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
e670: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
e680: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
e690: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
e6a0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
e6b0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
e6c0: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
e6d0: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
e6e0: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
e6f0: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
e700: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
e710: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
e720: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
e730: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
e740: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
e750: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
e760: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e770: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
e780: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
e790: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
e7a0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
e7b0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
e7c0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e7d0: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
e7e0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
e7f0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
e800: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e810: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
e820: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
e830: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
e840: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
e850: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
e860: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
e870: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
e880: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
e890: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e8a0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
e8b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
e8c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
e8d0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
e8e0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
e8f0: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
e900: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
e910: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
e920: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
e930: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
e940: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
e950: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
e960: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
e970: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
e980: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
e990: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
e9a0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
e9b0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
e9c0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
e9d0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
e9e0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e9f0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
ea00: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
ea10: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
ea20: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ea30: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
ea40: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
ea50: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
ea60: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
ea70: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
ea80: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
ea90: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
eaa0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
eab0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
eac0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ead0: 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
eae0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
eaf0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
eb00: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
eb10: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
eb20: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
eb30: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
eb40: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
eb50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
eb60: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
eb70: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
eb80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
eb90: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
eba0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
ebb0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
ebc0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
ebd0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
ebe0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
ebf0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
ec00: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
ec10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
ec20: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
ec30: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
ec40: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
ec50: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
ec60: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
ec70: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
ec80: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
ec90: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
eca0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
ecb0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
ecc0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
ecd0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
ece0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ecf0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
ed00: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
ed10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
ed20: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
ed30: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
ed40: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
ed50: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
ed60: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
ed70: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
ed80: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
ed90: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
eda0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
edb0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
edc0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
edd0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
ede0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
edf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee00: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
ee10: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
ee20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
ee30: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
ee40: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
ee50: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
ee60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
ee70: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
ee80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ee90: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
eea0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
eeb0: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
eec0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
eed0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
eee0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
eef0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
ef00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
ef10: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
ef20: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
ef30: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
ef40: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
ef50: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
ef60: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
ef70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
ef80: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ef90: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
efa0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
efb0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
efc0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
efd0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
efe0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
eff0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
f000: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
f010: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
f020: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f030: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
f040: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f050: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
f060: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
f070: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f080: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
f090: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
f0a0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
f0b0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
f0c0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
f0d0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
f0e0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
f0f0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
f100: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
f110: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
f120: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
f130: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f140: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
f150: 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
f160: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
f170: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
f180: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
f190: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
f1a0: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
f1b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f1c0: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
f1d0: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
f1e0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
f1f0: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
f200: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
f210: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
f220: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
f230: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
f240: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
f250: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
f260: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
f270: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
f280: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
f290: 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
f2a0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
f2b0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
f2c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
f2d0: 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
f2e0: 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
f2f0: 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
f300: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
f310: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f320: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
f330: 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
f340: 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
f350: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
f360: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
f370: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
f380: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
f390: 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
f3a0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
f3b0: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
f3c0: 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
f3d0: 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
f3e0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
f3f0: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
f400: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
f410: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
f420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
f430: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
f440: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
f450: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f460: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
f470: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
f480: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
f490: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
f4a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f4b0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
f4c0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
f4d0: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
f4e0: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
f4f0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
f500: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
f510: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
f520: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
f530: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
f540: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f550: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
f560: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f570: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
f580: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
f590: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
f5a0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
f5b0: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
f5c0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f5d0: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
f5e0: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
f5f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
f600: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
f610: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
f620: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
f630: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
f640: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
f650: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
f660: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f670: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
f680: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
f690: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
f6a0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
f6b0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
f6c0: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
f6d0: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
f6e0: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
f6f0: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
f700: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
f710: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
f720: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
f730: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
f740: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
f750: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
f760: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
f770: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
f780: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
f790: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
f7a0: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
f7b0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
f7c0: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
f7d0: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
f7e0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
f7f0: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
f800: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
f810: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
f820: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
f830: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
f840: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
f850: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
f860: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
f870: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
f880: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
f890: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
f8a0: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
f8b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
f8c0: 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
f8d0: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
f8e0: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
f8f0: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
f900: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
f910: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
f920: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
f930: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
f940: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
f950: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
f960: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
f970: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
f980: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
f990: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
f9a0: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
f9b0: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
f9c0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
f9d0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
f9e0: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
f9f0: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
fa00: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
fa10: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
fa20: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
fa30: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
fa40: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
fa50: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
fa60: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
fa70: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
fa80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
fa90: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
faa0: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
fab0: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
fac0: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
fad0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
fae0: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
faf0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
fb00: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
fb10: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
fb20: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
fb30: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
fb40: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
fb50: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
fb60: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
fb70: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
fb80: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
fb90: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
fba0: 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
fbb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
fbc0: 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
fbd0: 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
fbe0: 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
fbf0: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
fc00: 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
fc10: 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
fc20: 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
fc30: 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
fc40: 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
fc50: 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
fc60: 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
fc70: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
fc80: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
fc90: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
fca0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
fcb0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
fcc0: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
fcd0: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
fce0: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
fcf0: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
fd00: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
fd10: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
fd20: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
fd30: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
fd40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fd50: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
fd60: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
fd70: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
fd80: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
fd90: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
fda0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
fdb0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
fdc0: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
fdd0: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
fde0: 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
fdf0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
fe00: 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
fe10: 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
fe20: 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
fe30: 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
fe40: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
fe50: 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
fe60: 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
fe70: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
fe80: 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
fe90: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
fea0: 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
feb0: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
fec0: 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
fed0: 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
fee0: 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
fef0: 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
ff00: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
ff10: 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
ff20: 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
ff30: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
ff40: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
ff50: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
ff60: 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
ff70: 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
ff80: 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
ff90: 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
ffa0: 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
ffb0: 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
ffc0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
ffd0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ffe0: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
fff0: 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
10000 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
10010 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10020 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
10030 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
10040 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
10050 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
10060 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
10070 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
10080 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
10090 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
100a0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
100b0 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
100c0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
100d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
100e0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
100f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
10100 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10110 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
10120 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
10130 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
10140 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10150 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
10160 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
10170 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
10180 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
10190 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
101a0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
101b0 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
101c0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
101d0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
101e0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
101f0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
10200 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
10210 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
10220 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
10230 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
10240 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
10250 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
10260 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
10270 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
10280 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10290 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
102a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
102b0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
102c0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
102d0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
102e0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
102f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10300 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10310 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
10320 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
10330 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
10340 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
10350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10360 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
10370 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
10380 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
10390 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
103a0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
103b0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
103c0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
103d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
103e0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
103f0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
10400 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10410 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10420 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10430 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10440 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10450 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10460 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10470 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10480 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10490 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
104a0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
104b0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
104c0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
104d0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
104e0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
104f0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
10500 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
10510 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
10520 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
10530 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10540 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10550 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10560 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10570 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10580 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10590 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
105a0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
105b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
105c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
105d0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
105e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
105f0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
10600 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10610 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10620 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10630 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10640 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10650 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
10660 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
10670 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
10680 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
10690 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
106a0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
106b0 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
106c0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
106d0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
106e0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
106f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10700 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10710 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10720 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10730 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10740 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10750 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
10760 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
10770 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10780 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
10790 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
107a0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
107b0 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
107c0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
107d0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
107e0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
107f0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
10800 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
10810 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
10820 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
10830 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10840 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10850 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
10860 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10870 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
10880 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
10890 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
108a0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
108b0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
108c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
108d0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
108e0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
108f0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
10900 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
10910 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10920 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
10930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
10940 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
10950 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
10960 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
10970 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
10980 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
10990 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
109a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
109b0 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
109c0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
109d0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
109e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
109f0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
10a00 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
10a10 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
10a20 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
10a30 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
10a40 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
10a50 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10a60 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
10a70 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
10a80 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
10a90 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
10aa0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
10ab0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
10ac0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
10ad0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
10ae0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
10af0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
10b00 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
10b10 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
10b20 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
10b30 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
10b40 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10b50 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
10b60 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
10b70 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
10b80 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
10b90 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
10ba0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10bb0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
10bc0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
10bd0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
10be0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
10bf0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
10c00 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
10c10 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
10c20 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
10c30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
10c40 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
10c50 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
10c60 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
10c70 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
10c80 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
10c90 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
10ca0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
10cb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
10cc0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
10cd0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
10ce0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
10cf0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
10d00 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
10d10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10d20 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
10d30 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
10d40 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
10d50 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
10d60 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
10d70 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
10d80 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
10d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10da0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
10db0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
10dc0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
10dd0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
10de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
10df0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
10e00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
10e10 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
10e20 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
10e30 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
10e40 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10e50 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
10e60 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10e70 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
10e80 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
10e90 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
10ea0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
10eb0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
10ec0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
10ed0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
10ee0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
10ef0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10f00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10f10 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
10f20 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
10f30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
10f40 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
10f50 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
10f60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10f70 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
10f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10f90 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
10fa0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10fb0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10fc0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10fd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10fe0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
10ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
11000 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11010 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11020 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
11030 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
11040 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11050 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11060 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11070 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
11080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11090 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
110a0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
110b0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
110c0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
110d0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
110e0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
110f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11100 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
11110 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
11120 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
11130 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
11140 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11150 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
11160 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11170 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
11180 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11190 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
111a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
111b0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
111c0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
111d0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
111e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
111f0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11200 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11210 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
11220 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
11230 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
11240 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
11250 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11260 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11270 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11280 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11290 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
112a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
112b0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
112c0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
112d0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
112e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
112f0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
11300 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
11310 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
11320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11330 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11350 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
11360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11370 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
11380 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
11390 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
113a0 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
113b0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
113c0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
113d0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
113e0 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
113f0 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
11400 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
11410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11430 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
11440 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
11450 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
11460 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
11470 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
11480 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11490 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
114a0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
114b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
114c0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
114d0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
114e0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
114f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11500 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
11510 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
11520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11530 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11540 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
11550 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
11560 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
11570 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
11580 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
11590 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
115a0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
115b0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
115c0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
115d0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
115e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
115f0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11600 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11610 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
11620 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11630 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
11640 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
11650 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
11660 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
11670 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
11680 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
11690 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
116a0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
116b0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
116c0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
116d0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
116e0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
116f0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
11700 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
11710 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
11720 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
11730 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
11740 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
11750 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
11760 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
11770 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
11780 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
11790 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
117a0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
117b0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
117c0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
117d0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
117e0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
117f0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11800 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
11810 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
11820 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
11830 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
11840 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
11850 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
11860 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
11870 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
11880 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11890 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
118a0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
118b0 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
118c0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
118d0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
118e0 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
118f0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
11900 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
11910 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
11920 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
11930 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
11940 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
11950 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
11960 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
11970 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
11980 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
11990 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
119a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
119b0 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
119c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
119d0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
119e0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
119f0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
11a00 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
11a10 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
11a20 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
11a30 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
11a40 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
11a50 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
11a60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
11a70 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
11a80 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
11a90 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
11aa0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
11ab0 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
11ac0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
11ad0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
11ae0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
11af0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
11b00 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
11b10 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
11b20 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11b30 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
11b40 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
11b50 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
11b60 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
11b70 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
11b80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
11b90 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
11ba0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
11bb0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
11bc0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
11bd0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
11be0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
11bf0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
11c00 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
11c10 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
11c20 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
11c30 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
11c40 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
11c50 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
11c60 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
11c70 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
11c80 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
11c90 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
11ca0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
11cb0 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
11cc0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
11cd0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
11ce0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
11cf0 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
11d00 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
11d10 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
11d20 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
11d30 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
11d40 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
11d50 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
11d60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
11d70 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
11d80 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
11d90 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
11da0 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
11db0 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
11dc0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
11dd0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
11de0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
11df0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
11e00 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
11e10 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
11e20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
11e30 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
11e40 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
11e50 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
11e60 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
11e70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11e80 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
11e90 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
11ea0 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
11eb0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
11ec0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
11ed0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
11ee0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11ef0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
11f00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11f10 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
11f20 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
11f30 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
11f40 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
11f50 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
11f60 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
11f70 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
11f80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11f90 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
11fa0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
11fb0 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
11fc0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11fd0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
11fe0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
11ff0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
12000 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
12010 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
12020 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
12030 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
12040 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
12050 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
12060 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
12070 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12080 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
12090 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
120a0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
120b0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
120c0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
120d0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
120e0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
120f0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
12100 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
12110 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
12120 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
12130 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
12140 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12150 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
12160 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
12170 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
12180 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
12190 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
121a0 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
121b0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
121c0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
121d0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
121e0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
121f0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
12200 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
12210 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
12220 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12230 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
12240 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12250 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
12260 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
12270 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
12280 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12290 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
122a0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
122b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
122c0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
122d0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
122e0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
122f0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
12300 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
12310 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12320 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
12330 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
12340 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12350 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
12360 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12370 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12380 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12390 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
123a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
123b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
123c0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
123d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
123e0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
123f0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
12400 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12410 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12420 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
12430 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12440 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
12450 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
12460 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12470 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
12480 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12490 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
124a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
124b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
124c0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
124d0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
124e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
124f0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
12500 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12510 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12530 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12540 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12550 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12560 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12570 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12580 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12590 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
125a0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
125b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
125c0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
125d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
125e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
125f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
12600 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12610 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
12620 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12630 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
12640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12650 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12660 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12670 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12680 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12690 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
126a0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
126b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
126c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
126d0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
126e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
126f0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12700 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12710 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12720 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
12730 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12740 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12750 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12760 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12770 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
12780 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
12790 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
127a0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
127b0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
127c0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
127d0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
127e0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
127f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12800 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12810 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12820 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12830 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12840 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12850 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
12860 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
12870 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
12880 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
12890 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
128a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
128b0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
128c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
128d0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
128e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
128f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
12900 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
12910 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12920 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
12930 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12940 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
12950 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12960 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
12970 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
12980 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
12990 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
129a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
129b0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
129c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
129d0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
129e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
129f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
12a00 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
12a10 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
12a20 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
12a30 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
12a40 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
12a50 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
12a60 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
12a70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12a80 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
12a90 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12aa0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
12ab0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
12ac0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
12ad0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
12ae0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
12af0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
12b00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
12b10 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
12b20 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
12b30 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
12b40 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
12b50 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
12b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12b70 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
12b80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12b90 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
12ba0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12bb0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12bc0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12bd0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
12be0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
12bf0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
12c00 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
12c10 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
12c20 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
12c30 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
12c40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12c50 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
12c60 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
12c70 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
12c80 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
12c90 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
12ca0 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
12cb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12cc0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
12cd0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12ce0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
12cf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12d00 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12d10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12d20 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12d30 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
12d40 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
12d50 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
12d60 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
12d70 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
12d80 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
12d90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
12da0 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
12db0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12dc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
12dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12de0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
12df0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
12e00 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
12e10 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12e20 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
12e30 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
12e40 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
12e50 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
12e60 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
12e70 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
12e80 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
12e90 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
12ea0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
12eb0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
12ec0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
12ed0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
12ee0 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
12ef0 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
12f00 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
12f10 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
12f20 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
12f30 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
12f40 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
12f50 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
12f60 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
12f70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12f80 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
12f90 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
12fa0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
12fb0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
12fc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
12fd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
12fe0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
12ff0 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
13000 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
13010 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
13020 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
13030 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
13040 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
13050 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
13060 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
13070 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
13080 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13090 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
130a0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
130b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
130c0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
130d0 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
130e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
130f0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
13100 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
13110 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
13120 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
13130 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13140 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
13150 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
13160 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
13170 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
13180 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
13190 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
131a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
131b0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
131c0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
131d0 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
131e0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
131f0 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
13200 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
13210 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
13220 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
13230 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
13240 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
13250 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
13260 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
13270 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
13280 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13290 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
132a0 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  nt. If non-zero,
132b0 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e   then.** URI han
132c0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
132d0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
132e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
132f0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
13300 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f  ndling.** is glo
13310 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20  bally disabled. 
13320 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
13330 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13340 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
13350 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
13360 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
13370 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
13380 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
13390 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
133a0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
133b0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
133c0 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
133d0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
133e0 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
133f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13400 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
13410 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
13420 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
13430 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
13440 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20  n is opened. If 
13450 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
13460 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
13470 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
13480 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
13490 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
134a0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
134b0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
134c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
134d0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
134e0 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49   By default, URI
134f0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13500 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
13510 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
13520 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
13530 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
13540 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
13550 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
13560 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
13570 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13580 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
13590 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
135a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
135b0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
135c0 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
135d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
135e0 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
135f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
13600 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
13610 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
13620 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
13630 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
13640 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
13650 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
13660 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
13670 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
13680 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
13690 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
136a0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
136b0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
136c0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
136d0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
136e0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
136f0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
13700 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13710 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
13720 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
13730 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
13740 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
13750 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
13760 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
13770 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
13780 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
13790 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
137a0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
137b0 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69  ion.** malfuncti
137c0 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  on when the opti
137d0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
137e0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
137f0 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
13800 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
13810 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
13820 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
13830 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
13840 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
13850 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
13860 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
13870 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
13880 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
13890 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
138a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
138b0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
138c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
138d0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
138e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
138f0 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
13900 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
13910 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
13920 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
13930 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
13940 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
13950 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
13960 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
13970 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
13980 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
13990 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
139a0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
139b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
139c0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
139d0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
139e0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
139f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13a00 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
13a10 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
13a20 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
13a30 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
13a40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13a50 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
13a60 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
13a70 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
13a80 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
13a90 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
13aa0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
13ab0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
13ac0 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
13ad0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
13ae0 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
13af0 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
13b00 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
13b10 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
13b20 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
13b30 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
13b40 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
13b50 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
13b60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
13b70 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
13b80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b90 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
13ba0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13bb0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
13bc0 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
13bd0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
13be0 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
13bf0 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
13c00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
13c10 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
13c20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
13c30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
13c40 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
13c50 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
13c60 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
13c70 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
13c80 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
13c90 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
13ca0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
13cb0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
13cc0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
13cd0 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
13ce0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
13cf0 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
13d00 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
13d10 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
13d20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
13d30 68 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64  his case..** </d
13d40 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
13d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13d60 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
13d70 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
13d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13d90 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
13da0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
13db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13dc0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
13dd0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
13de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13df0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
13e00 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
13e10 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
13e20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13e30 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
13e40 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
13e50 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
13e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13e70 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
13e80 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
13e90 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
13ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13eb0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
13ec0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
13ed0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
13ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13ef0 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
13f00 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
13f10 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
13f20 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
13f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13f40 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
13f50 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
13f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13f70 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
13f80 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
13f90 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
13fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13fb0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
13fc0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
13fd0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13fe0 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
13ff0 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
14000 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
14010 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
14020 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
14030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14040 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
14050 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
14060 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14070 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
14080 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
14090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
140a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
140b0 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
140c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
140d0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
140e0 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
140f0 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
14100 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14110 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
14120 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
14130 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14140 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
14150 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
14160 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
14170 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14180 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14190 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
141a0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
141b0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
141c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
141d0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
141e0 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
141f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14200 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
14210 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
14220 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f  log, void* */../
14230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
14240 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
14250 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
14260 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
14270 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
14280 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
14290 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
142a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
142b0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
142c0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
142d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
142e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
142f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
14300 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
14310 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14320 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
14330 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
14340 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
14350 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
14360 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
14370 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
14380 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
14390 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
143a0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
143b0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
143c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
143d0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
143e0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
143f0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
14400 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14410 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
14420 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
14430 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
14440 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
14450 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
14460 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
14470 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
14480 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
14490 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
144a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
144b0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
144c0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
144d0 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
144e0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
144f0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
14500 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
14510 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14520 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
14530 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
14540 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
14550 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
14560 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
14570 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
14580 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14590 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
145a0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
145b0 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
145c0 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
145d0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
145e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
145f0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
14600 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14610 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
14620 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
14630 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
14640 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
14650 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14660 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
14670 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
14680 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
14690 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
146a0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
146b0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
146c0 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
146d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
146e0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
146f0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
14700 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
14710 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14720 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
14730 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
14740 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
14750 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
14760 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
14770 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
14780 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
14790 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
147a0 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
147b0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
147c0 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
147d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
147e0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
147f0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
14800 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
14810 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
14820 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
14830 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
14840 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
14850 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
14860 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
14870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14880 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
14890 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
148a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
148b0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
148c0 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
148d0 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
148e0 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
148f0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
14900 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
14910 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
14920 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
14930 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14940 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
14950 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
14960 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
14970 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14980 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
14990 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
149a0 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
149b0 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
149c0 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
149d0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
149e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
149f0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
14a00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
14a10 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
14a20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14a30 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
14a40 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
14a50 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
14a60 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
14a70 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
14a80 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
14a90 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
14aa0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
14ab0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
14ac0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
14ad0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
14ae0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
14af0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
14b00 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
14b10 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
14b20 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
14b30 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
14b40 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
14b50 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
14b60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
14b70 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14b80 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
14b90 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
14ba0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
14bb0 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
14bc0 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
14bd0 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
14be0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
14bf0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14c00 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
14c10 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
14c20 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
14c30 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
14c40 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
14c50 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
14c60 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
14c70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
14c80 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
14c90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
14ca0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
14cb0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
14cc0 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
14cd0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
14ce0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
14cf0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
14d00 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
14d10 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14d20 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
14d30 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
14d40 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
14d50 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
14d60 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
14d70 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
14d80 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
14d90 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
14da0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14db0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
14dc0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
14dd0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
14de0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
14df0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
14e00 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
14e10 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
14e20 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
14e30 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
14e40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14e50 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
14e60 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
14e70 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
14e80 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
14e90 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
14ea0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
14eb0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
14ec0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
14ed0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
14ee0 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
14ef0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
14f00 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
14f10 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
14f20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
14f30 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
14f40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14f50 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
14f60 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
14f70 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
14f80 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
14f90 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
14fa0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
14fb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
14fc0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
14fd0 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
14fe0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
14ff0 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
15000 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
15010 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
15020 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
15030 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
15040 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
15050 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
15060 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
15070 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
15080 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
15090 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
150a0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
150b0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
150c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
150d0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
150e0 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
150f0 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
15100 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
15110 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
15120 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
15130 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
15140 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
15150 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
15160 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
15170 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
15180 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
15190 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
151a0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
151b0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
151c0 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
151d0 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
151e0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
151f0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
15200 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
15210 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
15220 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
15230 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
15240 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
15250 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
15260 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
15270 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15280 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
15290 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
152a0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
152b0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
152c0 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
152d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
152e0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
152f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15300 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
15310 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
15320 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
15330 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
15340 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
15350 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
15360 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
15370 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
15380 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
15390 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
153a0 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
153b0 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
153c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
153d0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
153e0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
153f0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
15400 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
15410 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
15420 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
15430 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
15440 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
15450 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
15460 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
15470 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
15480 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
15490 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
154a0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
154b0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
154c0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
154d0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
154e0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
154f0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
15500 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
15510 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
15520 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
15530 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
15540 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
15550 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
15560 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
15570 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
15580 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
15590 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
155a0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
155b0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
155c0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
155d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
155e0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
155f0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
15600 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
15610 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
15620 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
15630 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
15640 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
15650 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
15660 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
15670 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
15680 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
15690 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
156a0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
156b0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
156c0 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
156d0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
156e0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
156f0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
15700 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
15710 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
15720 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
15730 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
15740 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
15750 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
15760 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
15770 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
15780 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
15790 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
157a0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
157b0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
157c0 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
157d0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
157e0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
157f0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
15800 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
15810 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
15820 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
15830 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
15840 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
15850 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
15860 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
15870 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
15880 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
15890 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
158a0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
158b0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
158c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
158d0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
158e0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
158f0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
15900 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
15910 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
15920 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
15930 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
15940 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
15950 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
15960 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
15970 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
15980 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
15990 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
159a0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
159b0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
159c0 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
159d0 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
159e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
159f0 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
15a00 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
15a10 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15a20 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
15a30 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
15a40 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
15a50 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
15a60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
15a70 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
15a80 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
15a90 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
15aa0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
15ab0 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
15ac0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
15ad0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
15ae0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
15af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
15b00 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
15b10 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
15b20 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
15b30 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
15b40 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
15b50 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
15b60 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
15b70 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
15b80 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
15b90 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
15ba0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
15bb0 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
15bc0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
15bd0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
15be0 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
15bf0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15c00 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
15c10 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
15c20 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
15c30 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
15c40 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
15c50 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
15c60 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
15c70 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
15c80 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
15c90 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
15ca0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
15cb0 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
15cc0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
15cd0 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
15ce0 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
15cf0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
15d00 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
15d10 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
15d20 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
15d30 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
15d40 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
15d50 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
15d60 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
15d70 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
15d80 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
15d90 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
15da0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
15db0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
15dc0 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
15dd0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
15de0 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
15df0 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
15e00 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
15e10 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
15e20 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
15e30 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
15e40 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
15e50 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
15e60 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
15e70 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
15e80 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
15e90 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
15ea0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
15eb0 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
15ec0 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
15ed0 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
15ee0 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
15ef0 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
15f00 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
15f10 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
15f20 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
15f30 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
15f40 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
15f50 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
15f60 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
15f70 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
15f80 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
15f90 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
15fa0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
15fb0 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
15fc0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
15fd0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
15fe0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
15ff0 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
16000 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
16010 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
16020 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
16030 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
16040 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16050 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
16060 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
16070 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
16080 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
16090 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
160a0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
160b0 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
160c0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
160d0 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
160e0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
160f0 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
16100 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
16110 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
16120 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
16130 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
16140 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
16150 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
16160 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
16170 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
16180 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
16190 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
161a0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
161b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
161c0 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
161d0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
161e0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
161f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
16200 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
16210 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
16220 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
16230 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
16240 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
16250 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
16260 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
16270 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
16280 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
16290 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
162a0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
162b0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
162c0 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
162d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
162e0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
162f0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
16300 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
16310 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
16320 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
16330 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
16340 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
16350 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
16360 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
16370 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
16380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16390 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
163a0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
163b0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
163c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
163d0 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
163e0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
163f0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
16400 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
16410 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
16420 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
16430 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
16440 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
16450 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
16460 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16470 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16480 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
16490 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
164a0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
164b0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
164c0 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
164d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
164e0 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
164f0 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
16500 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
16510 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
16520 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
16530 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
16540 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
16550 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
16560 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
16570 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
16580 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
16590 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
165a0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
165b0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
165c0 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
165d0 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
165e0 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
165f0 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
16600 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
16610 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
16620 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
16630 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
16640 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
16650 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
16660 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
16670 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
16680 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
16690 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
166a0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
166b0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
166c0 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
166d0 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
166e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
166f0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
16700 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
16710 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
16720 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
16730 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
16740 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
16750 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
16760 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
16770 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
16780 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
16790 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
167a0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
167b0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
167c0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
167d0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
167e0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
167f0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
16800 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
16810 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
16820 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
16830 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
16840 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
16850 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
16860 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
16870 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
16880 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
16890 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
168a0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
168b0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
168c0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
168d0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
168e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
168f0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16900 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
16920 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
16930 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
16940 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
16950 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
16960 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
16970 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
16980 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
16990 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
169a0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
169b0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
169c0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
169d0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
169e0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
169f0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
16a00 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
16a10 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
16a20 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
16a30 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
16a40 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
16a50 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
16a60 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
16a70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
16a80 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
16a90 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
16aa0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
16ab0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
16ac0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
16ad0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
16ae0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
16af0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
16b00 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
16b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16b20 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
16b30 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
16b40 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
16b50 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
16b60 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
16b70 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
16b80 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
16b90 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
16ba0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
16bb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16bc0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
16bd0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
16be0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
16bf0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
16c00 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
16c10 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
16c20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
16c30 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
16c40 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
16c50 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
16c60 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
16c70 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
16c80 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
16c90 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
16ca0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
16cb0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
16cc0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
16cd0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
16ce0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
16cf0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
16d00 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
16d10 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
16d20 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
16d30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
16d40 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
16d50 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
16d60 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
16d70 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
16d80 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
16d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16da0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
16db0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
16dc0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
16dd0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
16de0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
16df0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
16e00 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
16e10 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
16e20 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
16e30 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
16e40 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
16e50 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
16e60 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
16e70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16e80 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
16e90 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
16ea0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
16eb0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
16ec0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
16ed0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
16ee0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
16ef0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
16f00 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
16f10 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
16f20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16f30 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
16f40 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
16f50 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
16f60 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
16f70 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
16f80 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
16f90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
16fa0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
16fb0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
16fc0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
16fd0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
16fe0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
16ff0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
17000 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
17010 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
17020 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
17030 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
17040 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
17050 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
17060 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
17070 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
17080 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17090 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
170a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
170b0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
170c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
170d0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
170e0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
170f0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
17100 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
17110 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
17120 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
17130 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
17140 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
17150 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
17160 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
17170 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
17180 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
17190 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
171a0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
171b0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
171c0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
171d0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
171e0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
171f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
17200 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
17210 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
17220 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
17230 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
17240 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
17250 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
17260 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
17270 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
17280 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
17290 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
172a0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
172b0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
172c0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
172d0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
172e0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
172f0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
17300 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
17310 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
17320 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
17330 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
17340 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
17350 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
17360 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
17370 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
17380 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
17390 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
173a0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
173b0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
173c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
173d0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
173e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
173f0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
17400 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
17410 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
17420 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
17430 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
17440 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
17450 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
17460 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17470 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
17480 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
17490 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
174a0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
174b0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
174c0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
174d0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
174e0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
174f0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
17500 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
17510 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
17520 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
17530 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
17540 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
17550 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
17560 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
17570 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
17580 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
17590 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
175a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
175b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
175c0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
175d0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
175e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
175f0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
17600 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
17610 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
17620 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
17630 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
17640 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
17650 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
17660 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
17670 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
17680 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
17690 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
176a0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
176b0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
176c0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
176d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
176e0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
176f0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
17700 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
17710 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
17720 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
17730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17740 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
17750 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
17760 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
17770 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
17780 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
17790 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
177a0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
177b0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
177c0 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
177d0 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
177e0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
177f0 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
17800 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
17810 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
17820 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
17830 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
17840 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
17850 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
17860 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
17870 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
17880 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
17890 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
178a0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
178b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
178c0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
178d0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
178e0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
178f0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
17900 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
17910 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
17920 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17930 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
17940 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
17950 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
17960 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
17970 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
17980 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
17990 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
179a0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
179b0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
179c0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
179d0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
179e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
179f0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
17a00 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
17a10 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
17a20 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
17a30 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
17a40 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
17a50 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
17a60 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
17a70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
17a80 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
17a90 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
17aa0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
17ab0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
17ac0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17ad0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
17ae0 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
17af0 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
17b00 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
17b10 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
17b20 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
17b30 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
17b40 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
17b50 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
17b60 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
17b70 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
17b80 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
17b90 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
17ba0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
17bb0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
17bc0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
17bd0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
17be0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
17bf0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
17c00 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
17c10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
17c20 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
17c30 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
17c40 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
17c50 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
17c60 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
17c70 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
17c80 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
17c90 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
17ca0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
17cb0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
17cc0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
17cd0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
17ce0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
17cf0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
17d00 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
17d10 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
17d20 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
17d30 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
17d40 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
17d50 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
17d60 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
17d70 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
17d80 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
17d90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
17da0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
17db0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
17dc0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
17dd0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
17de0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
17df0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
17e00 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
17e10 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
17e20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
17e30 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
17e40 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17e50 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
17e60 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
17e70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
17e80 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
17e90 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
17ea0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
17eb0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
17ec0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
17ed0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
17ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
17ef0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
17f00 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
17f10 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
17f20 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
17f30 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
17f40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17f50 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
17f60 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
17f70 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
17f80 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
17f90 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
17fa0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
17fb0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
17fc0 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
17fd0 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
17fe0 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
17ff0 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
18000 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
18010 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
18020 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
18030 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
18040 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
18050 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
18060 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
18070 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
18080 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
18090 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
180a0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
180b0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
180c0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
180d0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
180e0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
180f0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
18100 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
18110 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
18120 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
18130 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
18140 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
18150 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
18160 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
18170 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18180 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
18190 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
181a0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
181b0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
181c0 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
181d0 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
181e0 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
181f0 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
18200 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
18210 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
18220 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
18230 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
18240 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
18250 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
18260 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
18270 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
18280 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
18290 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
182a0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
182b0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
182c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
182d0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
182e0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
182f0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
18300 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
18310 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
18320 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
18330 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
18340 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
18350 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
18360 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
18370 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
18380 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
18390 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
183a0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
183b0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
183c0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
183d0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
183e0 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
183f0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
18400 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
18410 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
18420 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
18430 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
18440 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18450 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
18460 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18470 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
18480 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18490 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
184a0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
184b0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
184c0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
184d0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
184e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
184f0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
18500 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
18510 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
18520 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
18530 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
18540 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
18550 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
18560 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
18570 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
18580 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
18590 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
185a0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
185b0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
185c0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
185d0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
185e0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
185f0 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
18600 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
18610 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
18620 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
18630 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
18640 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
18650 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
18660 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
18670 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
18680 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
18690 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
186a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
186b0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
186c0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
186d0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
186e0 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
186f0 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
18700 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
18710 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
18720 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
18730 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
18740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18750 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
18760 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
18770 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
18780 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
18790 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
187a0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
187b0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
187c0 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
187d0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
187e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
187f0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51  cleared.)^.*/.SQ
18800 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
18810 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
18820 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
18830 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
18840 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
18850 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
18860 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
18870 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
18880 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
18890 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
188a0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
188b0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
188c0 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
188d0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
188e0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
188f0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
18900 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
18910 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
18920 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
18930 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
18940 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18950 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
18960 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
18970 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
18980 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
18990 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
189a0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
189b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
189c0 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
189d0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
189e0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
189f0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
18a00 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
18a10 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
18a20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
18a30 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
18a40 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
18a50 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
18a60 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
18a70 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
18a80 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
18a90 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
18aa0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
18ab0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
18ac0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
18ad0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
18ae0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
18af0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
18b00 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
18b10 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
18b20 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
18b30 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
18b40 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
18b50 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
18b60 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
18b70 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
18b80 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
18b90 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
18ba0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
18bb0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
18bc0 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
18bd0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
18be0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
18bf0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
18c00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
18c10 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
18c20 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
18c30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
18c40 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
18c50 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
18c60 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
18c70 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
18c80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
18c90 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
18ca0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
18cb0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
18cc0 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
18cd0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
18ce0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
18cf0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
18d00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
18d10 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
18d20 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
18d30 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
18d40 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
18d50 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
18d60 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
18d70 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
18d80 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18d90 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
18da0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
18db0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
18dc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
18dd0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
18de0 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
18df0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
18e00 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
18e10 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
18e20 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
18e30 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
18e40 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
18e50 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
18e60 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
18e70 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
18e80 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
18e90 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
18ea0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18eb0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
18ec0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
18ed0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
18ee0 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
18ef0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
18f00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18f10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
18f20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
18f30 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
18f40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
18f50 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
18f60 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
18f70 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
18f80 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
18f90 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
18fa0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
18fb0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
18fc0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
18fd0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
18fe0 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
18ff0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19000 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
19010 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19020 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
19030 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19040 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
19050 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
19060 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
19070 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
19080 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
19090 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
190a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
190b0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
190c0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
190d0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
190e0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
190f0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
19100 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
19110 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
19120 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
19130 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
19140 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
19150 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
19160 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
19170 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19180 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
19190 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
191a0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
191b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
191c0 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
191d0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
191e0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
191f0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
19200 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
19210 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
19220 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
19230 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
19240 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
19250 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
19260 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
19270 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
19280 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
19290 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
192a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
192b0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
192c0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
192d0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
192e0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
192f0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
19300 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
19310 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
19320 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
19330 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
19340 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
19350 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19360 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
19370 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
19380 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
19390 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
193a0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
193b0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
193c0 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
193d0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
193e0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
193f0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
19400 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
19410 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
19420 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
19430 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
19440 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
19450 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
19460 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
19470 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
19480 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
19490 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
194a0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
194b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
194c0 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
194d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
194e0 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
194f0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
19500 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
19510 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
19520 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
19530 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
19540 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
19550 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
19560 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
19570 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
19580 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
19590 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
195a0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
195b0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
195c0 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
195d0 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
195e0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
195f0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
19600 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
19610 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
19620 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
19630 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
19640 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
19650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
19660 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
19670 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
19680 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
19690 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
196a0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
196b0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
196c0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
196d0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
196e0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
196f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19700 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
19710 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
19720 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
19730 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
19740 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
19750 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
19760 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
19770 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
19780 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
19790 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
197a0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
197b0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
197c0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
197d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
197e0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
197f0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
19800 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
19810 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
19820 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
19830 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
19840 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
19850 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
19860 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
19870 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
19880 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
19890 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
198a0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
198b0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
198c0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
198d0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
198e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
198f0 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
19900 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
19910 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
19920 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
19930 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
19940 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
19950 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
19960 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
19970 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
19980 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
19990 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
199a0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
199b0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
199c0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
199d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
199e0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
199f0 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
19a00 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
19a10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
19a20 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
19a30 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
19a40 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
19a50 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
19a60 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
19a70 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
19a80 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
19a90 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
19aa0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
19ab0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
19ac0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
19ad0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
19ae0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
19af0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
19b00 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
19b10 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
19b20 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
19b30 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
19b40 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
19b50 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
19b60 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
19b70 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
19b80 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
19b90 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
19ba0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
19bb0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
19bc0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
19bd0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
19be0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
19bf0 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
19c00 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
19c10 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
19c20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
19c30 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
19c40 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
19c50 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
19c60 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
19c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19c80 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
19c90 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
19ca0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
19cb0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
19cc0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
19cd0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
19ce0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
19cf0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
19d00 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
19d10 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
19d20 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
19d30 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
19d40 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
19d50 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
19d60 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
19d70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
19d80 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
19d90 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
19da0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
19db0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
19dc0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
19dd0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
19de0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
19df0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
19e00 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
19e10 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
19e20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
19e30 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
19e40 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
19e50 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
19e60 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
19e70 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
19e80 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
19e90 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
19ea0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
19eb0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
19ec0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
19ed0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
19ee0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
19ef0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
19f00 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
19f10 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
19f20 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
19f30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
19f40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19f50 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
19f60 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
19f70 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
19f80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
19f90 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
19fa0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
19fb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
19fc0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
19fd0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19fe0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
19ff0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1a000 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1a010 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1a020 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1a030 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1a040 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1a050 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1a060 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1a070 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a080 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1a090 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1a0a0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1a0b0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1a0c0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1a0d0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1a0e0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1a0f0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1a100 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a110 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1a120 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1a130 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1a140 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1a150 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a160 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1a170 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1a180 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1a190 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1a1a0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1a1b0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1a1c0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1a1d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a1e0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1a1f0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1a200 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1a210 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1a220 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1a230 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1a240 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1a250 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1a260 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1a270 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1a280 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1a290 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1a2a0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1a2b0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1a2c0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1a2d0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1a2e0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1a2f0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1a300 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1a310 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1a320 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1a330 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1a340 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1a350 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1a360 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1a370 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1a380 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1a390 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1a3a0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1a3b0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1a3c0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1a3d0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1a3e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1a3f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1a400 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1a410 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1a420 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1a430 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1a440 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1a450 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1a460 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1a470 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1a480 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a490 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1a4a0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1a4b0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1a4c0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1a4d0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1a4e0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1a4f0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1a500 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1a510 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1a520 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1a530 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1a540 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1a550 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1a560 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1a570 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1a580 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1a590 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1a5a0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1a5b0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1a5c0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1a5d0 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1a5e0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1a5f0 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1a600 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
1a610 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1a620 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1a630 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1a640 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
1a650 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1a660 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1a670 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1a680 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1a690 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1a6a0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1a6b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1a6c0 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1a6d0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1a6e0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1a6f0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1a700 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1a710 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1a720 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1a730 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1a740 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1a750 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1a760 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1a770 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1a780 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1a790 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1a7a0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1a7b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1a7c0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1a7d0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1a7e0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1a7f0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1a800 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1a810 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1a820 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1a830 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1a840 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1a850 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1a860 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1a870 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1a880 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1a890 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1a8a0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1a8b0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1a8c0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1a8d0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1a8e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1a8f0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1a900 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1a910 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1a920 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1a930 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1a940 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1a950 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1a960 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1a970 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1a980 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1a990 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1a9a0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1a9b0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1a9c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1a9d0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1a9e0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1a9f0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1aa00 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1aa10 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1aa20 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1aa30 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1aa40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1aa50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1aa60 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1aa70 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1aa80 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1aa90 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1aaa0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1aab0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1aac0 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1aad0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1aae0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1aaf0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1ab00 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1ab10 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1ab20 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1ab30 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1ab40 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1ab50 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1ab60 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1ab70 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1ab80 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1ab90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1aba0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1abb0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1abc0 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1abd0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1abe0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1abf0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1ac00 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1ac10 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1ac20 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1ac30 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1ac40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1ac50 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1ac60 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1ac70 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1ac80 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1ac90 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1aca0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1acb0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1acc0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1acd0 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1ace0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1acf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1ad00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1ad10 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1ad20 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1ad30 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1ad40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1ad50 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1ad60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1ad70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1ad80 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1ad90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ada0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1adb0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1adc0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1add0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1ade0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1adf0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1ae00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1ae10 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1ae20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1ae30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1ae40 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1ae50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1ae60 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1ae70 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1ae80 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1ae90 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1aea0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1aeb0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1aec0 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1aed0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1aee0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1aef0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1af00 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1af10 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1af20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1af30 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1af40 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1af50 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1af60 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1af70 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1af80 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1af90 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1afa0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1afb0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1afc0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1afd0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1afe0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1aff0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1b000 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1b010 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1b020 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1b030 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1b040 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1b050 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1b060 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1b070 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1b080 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1b090 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1b0a0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1b0b0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1b0c0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1b0d0 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1b0e0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1b0f0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1b100 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1b110 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1b120 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1b130 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1b140 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1b150 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1b160 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1b170 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1b180 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1b190 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1b1a0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1b1b0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1b1c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1b1d0 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1b1e0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1b1f0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1b200 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1b210 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1b220 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1b230 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1b240 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1b250 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1b260 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1b270 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1b280 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1b290 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1b2a0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1b2b0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1b2c0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1b2d0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1b2e0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1b2f0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1b300 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1b310 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1b320 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1b330 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1b340 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1b350 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1b360 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1b370 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1b380 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1b390 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1b3a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1b3b0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1b3c0 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1b3d0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1b3e0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1b3f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1b400 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1b410 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1b420 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1b430 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1b440 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1b450 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1b460 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1b470 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1b480 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1b490 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1b4a0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1b4b0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1b4c0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1b4d0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1b4e0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1b4f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1b500 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1b510 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1b520 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
1b530 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1b540 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
1b550 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
1b560 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1b570 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1b580 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1b590 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1b5a0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1b5b0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1b5c0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1b5d0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1b5e0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1b5f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1b600 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1b610 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1b620 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1b630 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1b640 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1b650 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1b660 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1b670 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1b680 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1b690 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1b6a0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1b6b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1b6c0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1b6d0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1b6e0 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1b6f0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1b700 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1b710 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1b720 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b730 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1b740 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1b750 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1b760 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1b770 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1b780 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1b790 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1b7a0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1b7b0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1b7c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1b7d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1b7e0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1b7f0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1b800 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1b810 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1b820 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1b830 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1b840 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1b850 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1b860 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1b870 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1b880 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1b890 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1b8a0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1b8b0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1b8c0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1b8d0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1b8e0 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1b8f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1b900 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1b910 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1b920 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1b930 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1b940 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1b950 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b960 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1b970 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1b980 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1b990 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1b9a0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1b9b0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
1b9c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
1b9d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1b9e0 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
1b9f0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1ba00 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1ba10 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1ba20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1ba30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1ba40 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1ba50 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
1ba60 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
1ba70 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
1ba80 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
1ba90 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
1baa0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
1bab0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
1bac0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
1bad0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1bae0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
1baf0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
1bb00 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
1bb10 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
1bb20 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1bb30 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1bb40 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1bb50 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1bb60 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1bb70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1bb80 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1bb90 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1bba0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1bbb0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1bbc0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1bbd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1bbe0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1bbf0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1bc00 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1bc10 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
1bc20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
1bc30 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
1bc40 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
1bc50 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
1bc60 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
1bc70 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
1bc80 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
1bc90 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
1bca0 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
1bcb0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1bcc0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
1bcd0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1bce0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
1bcf0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
1bd00 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
1bd10 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1bd20 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1bd30 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1bd40 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1bd50 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1bd60 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1bd70 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1bd80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1bd90 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1bda0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1bdb0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1bdc0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1bdd0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1bde0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1bdf0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1be00 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1be10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1be20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1be30 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1be40 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1be50 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1be60 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1be70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1be80 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1be90 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1bea0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1beb0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1bec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1bed0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1bee0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1bef0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1bf00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1bf10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1bf20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1bf30 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1bf40 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1bf50 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1bf60 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1bf70 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1bf80 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1bf90 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1bfa0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1bfb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1bfc0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1bfd0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1bfe0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1bff0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c000 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1c010 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1c020 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1c030 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1c040 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1c050 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1c060 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1c070 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1c080 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1c090 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1c0a0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1c0b0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1c0c0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1c0d0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1c0e0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1c0f0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1c100 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c110 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1c120 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1c130 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1c140 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1c150 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1c160 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1c170 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1c180 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1c190 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1c1a0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1c1b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1c1c0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1c1d0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1c1e0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1c1f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1c200 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1c210 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1c220 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1c230 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1c240 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c250 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1c260 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1c270 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1c280 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1c290 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1c2a0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1c2b0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1c2c0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1c2d0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1c2e0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1c2f0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1c300 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1c310 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1c320 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c330 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1c340 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1c350 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1c360 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c370 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1c380 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1c390 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1c3a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1c3b0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1c3c0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1c3d0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1c3e0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1c3f0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1c400 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1c410 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1c420 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1c430 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1c440 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1c450 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1c460 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1c470 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1c480 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1c490 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1c4a0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1c4b0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1c4c0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1c4d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1c4e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1c4f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1c500 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1c510 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1c520 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1c530 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1c540 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1c550 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1c560 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1c570 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1c580 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1c590 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1c5a0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1c5b0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1c5c0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1c5d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1c5e0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1c5f0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1c600 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1c610 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1c620 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1c630 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1c640 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1c650 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c660 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1c670 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1c680 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1c690 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1c6a0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1c6b0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1c6c0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1c6d0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1c6e0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1c6f0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1c700 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1c710 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1c720 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1c730 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1c740 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1c750 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1c760 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1c770 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1c780 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1c790 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1c7a0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1c7b0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1c7c0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1c7d0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1c7e0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1c7f0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1c800 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1c810 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1c820 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1c830 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1c840 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1c850 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1c860 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1c870 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1c880 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1c890 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1c8a0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1c8b0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1c8c0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1c8d0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1c8e0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1c8f0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1c900 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1c910 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1c920 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1c930 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1c940 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1c950 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1c960 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1c970 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1c980 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1c990 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1c9a0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1c9b0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1c9c0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1c9d0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1c9e0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1c9f0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1ca00 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1ca10 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1ca20 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1ca30 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1ca40 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1ca50 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1ca60 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1ca70 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1ca80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1ca90 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1caa0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1cab0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1cac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1cad0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1cae0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1caf0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1cb00 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1cb10 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1cb20 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1cb30 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1cb40 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1cb50 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1cb60 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1cb70 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1cb80 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1cb90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cba0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1cbb0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1cbc0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1cbd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cbe0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1cbf0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1cc00 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1cc10 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1cc20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1cc30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cc40 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1cc50 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1cc60 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1cc70 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1cc80 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1cc90 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1cca0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1ccb0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1ccc0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1ccd0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1cce0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1ccf0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1cd00 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1cd10 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1cd20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1cd30 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1cd40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1cd50 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1cd60 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1cd70 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1cd80 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1cd90 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1cda0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1cdb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1cdc0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1cdd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1cde0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1cdf0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1ce00 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1ce10 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1ce20 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1ce30 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1ce40 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1ce50 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1ce60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1ce70 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1ce80 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1ce90 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1cea0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1ceb0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1cec0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1ced0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1cee0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1cef0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1cf00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1cf10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1cf20 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1cf30 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1cf40 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1cf50 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1cf60 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1cf70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1cf80 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1cf90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1cfa0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1cfb0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1cfc0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1cfd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1cfe0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cff0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1d000 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1d010 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1d020 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1d030 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1d040 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1d050 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1d060 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1d070 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1d080 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1d090 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1d0a0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1d0b0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1d0c0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1d0d0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1d0e0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1d0f0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1d100 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1d110 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42   a [SQLITE_ROLLB
1d120 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  ACK | return cod
1d130 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b  e].** from the [
1d140 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
1d150 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
1d160 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
1d170 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
1d180 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
1d190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1d1a0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
1d1b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1d1c0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
1d1d0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
1d1e0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
1d1f0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
1d200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d210 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
1d220 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
1d230 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1d240 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
1d250 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
1d260 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1d270 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
1d280 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
1d290 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
1d2a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
1d2b0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
1d2c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1d2d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1d2e0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
1d2f0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1d300 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
1d310 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
1d320 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
1d330 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
1d340 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
1d350 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d360 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
1d370 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
1d380 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
1d390 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
1d3a0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
1d3b0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
1d3c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1d3d0 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
1d3e0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1d3f0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
1d400 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d410 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
1d420 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
1d430 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
1d440 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
1d450 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
1d460 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1d470 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
1d480 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1d490 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
1d4a0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
1d4b0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1d4c0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
1d4d0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
1d4e0 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
1d4f0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
1d500 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1d510 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
1d520 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1d530 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
1d540 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
1d550 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
1d560 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
1d570 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1d580 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1d590 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1d5a0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
1d5b0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1d5c0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1d5d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d5e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d5f0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1d600 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1d610 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1d620 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1d630 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1d640 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1d650 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d660 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d670 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1d680 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1d690 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d6a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1d6b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d6c0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1d6d0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1d6e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1d6f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1d700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d710 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1d720 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1d730 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1d740 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d750 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d760 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1d770 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1d780 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1d790 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d7a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d7b0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1d7c0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1d7d0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1d7e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d7f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d800 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1d810 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1d820 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1d830 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1d840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d850 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1d860 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1d870 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1d880 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d890 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1d8a0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1d8b0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1d8c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1d8d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d8e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d8f0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1d900 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1d910 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1d920 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1d930 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1d940 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1d950 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1d960 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1d970 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1d980 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1d990 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1d9a0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1d9b0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1d9c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d9d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1d9e0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1d9f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1da00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1da10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1da20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1da30 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1da40 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1da50 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1da60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1da70 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1da80 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1da90 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1daa0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1dab0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dac0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1dad0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1dae0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1daf0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1db00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1db10 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1db20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1db30 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1db40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1db50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1db60 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1db70 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1db80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1db90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1dba0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dbb0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1dbc0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1dbd0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1dbe0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1dbf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dc00 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1dc10 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1dc20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1dc30 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1dc40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dc50 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1dc60 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1dc70 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1dc80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1dc90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1dca0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1dcb0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
1dcc0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
1dcd0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1dce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1dcf0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1dd00 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1dd10 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1dd20 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1dd30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1dd40 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1dd50 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1dd60 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1dd70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1dd80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1dd90 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1dda0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1ddb0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1ddc0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ddd0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1dde0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1ddf0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1de00 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1de10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1de20 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1de30 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1de40 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1de50 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1de60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1de70 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1de80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1de90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1dea0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1deb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1dec0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1ded0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1dee0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1def0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1df00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1df10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1df20 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1df30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1df40 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1df50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1df60 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1df70 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1df80 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1df90 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1dfa0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dfb0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
1dfc0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
1dfd0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1dfe0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
1dff0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e000 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
1e010 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
1e020 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
1e030 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1e040 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
1e050 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
1e060 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1e070 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
1e080 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1e090 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
1e0a0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
1e0b0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
1e0c0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1e0d0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1e0e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
1e0f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1e100 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1e110 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
1e120 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
1e130 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
1e140 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
1e150 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
1e160 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
1e170 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
1e180 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1e190 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e1a0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
1e1b0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
1e1c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1e1d0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
1e1e0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
1e1f0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
1e200 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
1e210 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1e220 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
1e230 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
1e240 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
1e250 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
1e260 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
1e270 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
1e280 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
1e290 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
1e2a0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
1e2b0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
1e2c0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1e2d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1e2e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
1e2f0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
1e300 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
1e310 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1e320 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
1e330 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
1e340 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
1e350 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
1e360 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
1e370 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
1e380 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
1e390 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
1e3a0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
1e3b0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
1e3c0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
1e3d0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
1e3e0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
1e3f0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
1e400 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
1e410 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
1e420 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
1e430 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
1e440 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
1e450 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
1e460 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
1e470 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
1e480 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1e490 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
1e4a0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
1e4b0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
1e4c0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
1e4d0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
1e4e0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
1e4f0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
1e500 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1e510 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
1e520 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
1e530 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
1e540 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1e550 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1e560 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
1e570 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
1e580 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
1e590 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
1e5a0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
1e5b0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
1e5c0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1e5d0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1e5e0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1e5f0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1e600 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1e610 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1e620 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1e630 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1e640 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
1e650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e660 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1e670 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
1e680 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
1e690 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
1e6a0 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
1e6b0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
1e6c0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
1e6d0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1e6e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1e6f0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
1e700 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
1e710 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1e720 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
1e730 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1e740 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1e750 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1e760 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1e770 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1e780 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1e790 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
1e7a0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
1e7b0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
1e7c0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1e7d0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
1e7e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1e7f0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
1e800 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
1e810 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1e820 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1e830 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1e840 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1e850 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1e860 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1e870 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1e880 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1e890 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1e8a0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1e8b0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1e8c0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1e8d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1e8e0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1e8f0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1e900 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1e910 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1e920 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1e930 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1e940 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1e950 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1e960 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1e970 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1e980 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1e990 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1e9a0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1e9b0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1e9c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1e9d0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1e9e0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1e9f0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1ea00 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1ea10 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1ea20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1ea30 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1ea40 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1ea50 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1ea60 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1ea70 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1ea80 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1ea90 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1eaa0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1eab0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1eac0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1ead0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1eae0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1eaf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1eb00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1eb10 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1eb20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1eb30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1eb40 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1eb50 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1eb60 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1eb70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1eb80 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1eb90 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1eba0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1ebb0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1ebc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ebd0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1ebe0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1ebf0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1ec00 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1ec10 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1ec20 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
1ec30 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1ec40 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1ec50 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1ec60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1ec70 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1ec80 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1ec90 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1eca0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1ecb0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1ecc0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1ecd0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1ece0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1ecf0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1ed00 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1ed10 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1ed20 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1ed30 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1ed40 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1ed50 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1ed60 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1ed70 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1ed80 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1ed90 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1eda0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1edb0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1edc0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1edd0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1ede0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1edf0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1ee00 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1ee10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1ee20 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1ee30 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1ee40 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1ee50 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1ee60 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1ee70 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1ee80 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1ee90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1eea0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1eeb0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1eec0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1eed0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1eee0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1eef0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1ef00 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1ef10 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1ef20 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1ef30 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1ef40 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1ef50 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1ef60 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1ef70 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1ef80 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1ef90 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1efa0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1efb0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1efc0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1efd0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1efe0 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1eff0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1f000 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1f010 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1f020 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1f030 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1f040 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1f050 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1f060 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1f070 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1f080 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1f090 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1f0a0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1f0b0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1f0c0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1f0d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1f0e0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1f0f0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1f100 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1f110 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1f120 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1f130 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1f140 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1f150 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1f160 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1f170 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
1f180 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1f190 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
1f1a0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1f1b0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1f1c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1f1d0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1f1e0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1f1f0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1f200 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1f210 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1f220 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
1f230 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1f240 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
1f250 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1f260 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
1f270 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1f280 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1f290 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1f2a0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1f2b0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1f2c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1f2d0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1f2e0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1f2f0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1f300 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1f310 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1f320 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1f330 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1f340 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1f350 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1f360 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1f370 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1f380 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1f390 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1f3a0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1f3b0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1f3c0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1f3d0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1f3e0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1f3f0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1f400 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1f410 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1f420 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1f430 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1f440 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1f450 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1f460 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1f470 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1f480 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1f490 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1f4a0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1f4b0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1f4c0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
1f4d0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1f4e0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1f4f0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1f500 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1f510 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1f520 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1f530 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1f540 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1f550 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1f560 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1f570 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1f580 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1f590 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1f5a0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
1f5b0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1f5c0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
1f5d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1f5e0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
1f5f0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
1f600 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1f610 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1f620 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
1f630 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1f640 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
1f650 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1f660 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1f670 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
1f680 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
1f690 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
1f6a0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
1f6b0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
1f6c0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
1f6d0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1f6e0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
1f6f0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
1f700 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1f710 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
1f720 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1f730 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
1f740 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
1f750 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1f760 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
1f770 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
1f780 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1f790 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
1f7a0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1f7b0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
1f7c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1f7d0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
1f7e0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1f7f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1f800 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
1f810 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
1f820 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
1f830 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1f840 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
1f850 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
1f860 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1f870 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1f880 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
1f890 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f8a0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1f8b0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1f8c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f8d0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
1f8e0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
1f8f0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
1f900 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
1f910 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1f920 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f930 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1f940 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1f950 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1f960 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1f970 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1f980 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1f990 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1f9a0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1f9b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f9c0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
1f9d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1f9e0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
1f9f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1fa00 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
1fa10 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1fa20 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
1fa30 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1fa40 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1fa50 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1fa60 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1fa70 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1fa80 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1fa90 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1faa0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1fab0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1fac0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1fad0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1fae0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1faf0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1fb00 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1fb10 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1fb20 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1fb30 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1fb40 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1fb50 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1fb60 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1fb70 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1fb80 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1fb90 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1fba0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1fbb0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1fbc0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1fbd0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1fbe0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1fbf0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1fc00 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1fc10 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1fc20 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1fc30 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1fc40 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1fc50 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1fc60 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1fc70 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1fc80 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1fc90 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1fca0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1fcb0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1fcc0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1fcd0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1fce0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
1fcf0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
1fd00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
1fd10 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
1fd20 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
1fd30 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
1fd40 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1fd50 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
1fd60 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1fd70 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
1fd80 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
1fd90 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1fda0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1fdb0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
1fdc0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1fdd0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1fde0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
1fdf0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
1fe00 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
1fe10 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1fe20 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1fe30 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
1fe40 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
1fe50 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
1fe60 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
1fe70 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
1fe80 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
1fe90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1fea0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
1feb0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
1fec0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
1fed0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
1fee0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1fef0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
1ff00 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
1ff10 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
1ff20 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
1ff30 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
1ff40 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
1ff50 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
1ff60 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
1ff70 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
1ff80 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
1ff90 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
1ffa0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1ffb0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1ffc0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
1ffd0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
1ffe0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
1fff0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
20000 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
20010 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
20020 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
20030 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
20040 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
20050 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
20060 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
20070 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
20080 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
20090 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
200a0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
200b0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
200c0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
200d0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
200e0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
200f0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
20100 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
20110 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
20120 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
20130 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20140 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
20150 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
20160 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
20170 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
20180 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
20190 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
201a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
201b0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
201c0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
201d0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
201e0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
201f0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
20200 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
20210 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
20220 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
20230 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
20240 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
20250 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
20260 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
20270 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
20280 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
20290 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
202a0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
202b0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
202c0 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
202d0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
202e0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
202f0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
20300 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
20310 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
20320 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
20330 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
20340 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
20350 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
20360 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
20370 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
20380 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
20390 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
203a0 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
203b0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
203c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
203d0 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
203e0 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
203f0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
20400 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
20410 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
20420 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
20430 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
20440 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
20450 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
20460 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
20470 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
20480 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
20490 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
204a0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
204b0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
204c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
204d0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
204e0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
204f0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
20500 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
20510 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
20520 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
20530 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
20540 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
20550 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
20560 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
20570 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
20580 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
20590 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
205a0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
205b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
205c0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
205d0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
205e0 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
205f0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
20600 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
20610 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
20620 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
20630 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
20640 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
20650 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
20660 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
20670 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
20680 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
20690 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
206a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
206b0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
206c0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
206d0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
206e0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
206f0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
20700 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
20710 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
20720 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
20730 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20740 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
20750 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
20760 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
20770 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
20780 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
20790 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
207a0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
207b0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
207c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
207d0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
207e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
207f0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
20800 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
20810 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
20820 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
20830 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
20840 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20850 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
20860 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
20870 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
20880 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
20890 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
208a0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
208b0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
208c0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
208d0 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
208e0 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
208f0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
20900 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
20910 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
20920 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
20930 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
20940 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
20950 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
20960 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
20970 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
20980 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
20990 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
209a0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
209b0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
209c0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
209d0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
209e0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
209f0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
20a00 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
20a10 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
20a20 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
20a30 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
20a40 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
20a50 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
20a60 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
20a70 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
20a80 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
20a90 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
20aa0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
20ab0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
20ac0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
20ad0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
20ae0 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
20af0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20b00 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
20b10 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
20b20 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
20b30 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
20b40 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
20b50 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
20b60 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
20b70 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
20b80 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
20b90 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
20ba0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
20bb0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20bc0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
20bd0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
20be0 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
20bf0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
20c00 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
20c10 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
20c20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20c30 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
20c40 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
20c50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20c60 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
20c70 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
20c80 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
20c90 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
20ca0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
20cb0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
20cc0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
20cd0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
20ce0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
20cf0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
20d00 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
20d10 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
20d20 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
20d30 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
20d40 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
20d50 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
20d60 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
20d70 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
20d80 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
20d90 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
20da0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
20db0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
20dc0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
20dd0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
20de0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
20df0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
20e00 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
20e10 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
20e20 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
20e30 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
20e40 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
20e50 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
20e60 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
20e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
20e80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
20e90 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
20ea0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
20eb0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
20ec0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
20ed0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
20ee0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
20ef0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
20f00 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
20f10 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
20f20 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
20f30 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
20f40 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
20f50 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
20f60 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
20f70 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
20f80 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
20f90 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
20fa0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
20fb0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
20fc0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
20fd0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
20fe0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
20ff0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
21000 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
21010 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
21020 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
21030 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
21040 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
21050 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
21060 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
21070 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
21080 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
21090 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
210a0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
210b0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
210c0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
210d0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
210e0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
210f0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
21100 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
21110 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
21120 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21130 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
21140 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
21150 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
21160 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
21170 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
21180 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
21190 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
211a0 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
211b0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
211c0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
211d0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
211e0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
211f0 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
21200 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21210 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
21220 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
21230 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
21240 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
21250 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
21260 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
21270 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
21280 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
21290 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
212a0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
212b0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
212c0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
212d0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
212e0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
212f0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
21300 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
21310 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
21320 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
21330 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
21340 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
21350 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
21360 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
21370 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
21380 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
21390 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
213a0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
213b0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
213c0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
213d0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
213e0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
213f0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
21400 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
21410 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
21420 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
21430 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
21440 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
21450 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
21460 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
21470 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
21480 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
21490 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
214a0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
214b0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
214c0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
214d0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
214e0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
214f0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
21500 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
21510 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
21520 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
21530 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
21540 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
21550 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
21560 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
21570 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
21580 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
21590 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
215a0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
215b0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
215c0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
215d0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
215e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
215f0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
21600 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
21610 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
21620 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
21630 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
21640 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
21650 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
21660 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
21670 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21680 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
21690 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
216a0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
216b0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
216c0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
216d0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
216e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
216f0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
21700 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
21710 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
21720 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
21730 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21740 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21750 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
21760 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
21770 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
21780 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
21790 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
217a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
217b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
217c0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
217d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
217e0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
217f0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
21800 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
21810 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
21820 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
21830 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21840 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
21850 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
21860 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21870 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
21880 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
21890 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
218a0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
218b0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
218c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
218d0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
218e0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
218f0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
21900 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
21910 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
21920 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
21930 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
21940 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
21950 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
21960 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
21970 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
21980 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
21990 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
219a0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
219b0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
219c0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
219d0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
219e0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
219f0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
21a00 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
21a10 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
21a20 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
21a30 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
21a40 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
21a50 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
21a60 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
21a70 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
21a80 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
21a90 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
21aa0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
21ab0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
21ac0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
21ad0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
21ae0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
21af0 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
21b00 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21b10 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
21b20 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
21b30 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
21b40 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
21b50 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
21b60 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
21b70 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
21b80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
21b90 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
21ba0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
21bb0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
21bc0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
21bd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
21be0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
21bf0 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
21c00 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
21c10 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
21c20 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
21c30 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
21c40 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
21c50 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
21c60 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
21c70 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
21c80 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
21c90 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
21ca0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
21cb0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
21cc0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
21cd0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
21ce0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
21cf0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21d00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
21d10 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
21d20 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
21d30 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
21d40 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
21d50 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
21d60 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
21d70 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
21d80 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
21d90 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
21da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
21db0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
21dc0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
21dd0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
21de0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
21df0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
21e00 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
21e10 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
21e20 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
21e30 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
21e40 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
21e50 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
21e60 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
21e70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
21e80 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
21e90 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
21ea0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
21eb0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
21ec0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
21ed0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
21ee0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
21ef0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21f00 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
21f10 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
21f20 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
21f30 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
21f40 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
21f50 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
21f60 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
21f70 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
21f80 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
21f90 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
21fa0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
21fb0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
21fc0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
21fd0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
21fe0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
21ff0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
22000 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
22010 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
22020 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
22030 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22040 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
22050 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
22060 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
22070 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
22080 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
22090 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
220a0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
220b0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
220c0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
220d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
220e0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
220f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
22100 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
22110 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
22120 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
22130 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
22140 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
22150 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
22160 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
22170 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
22180 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  I int sqlite3_ur
22190 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
221a0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
221b0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
221c0 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
221d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
221e0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
221f0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
22200 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
22210 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
22220 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
22230 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
22240 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
22250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22260 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
22270 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
22280 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
22290 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
222a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
222b0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
222c0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
222d0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
222e0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
222f0 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
22300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
22310 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
22320 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
22330 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
22340 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
22350 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
22360 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
22370 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
22380 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
22390 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
223a0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
223b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
223c0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
223d0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
223e0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
223f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
22400 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
22410 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
22420 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
22430 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
22440 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
22450 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
22460 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
22470 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
22480 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
22490 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
224a0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
224b0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
224c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
224d0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
224e0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
224f0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
22500 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
22510 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
22520 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
22530 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
22540 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
22550 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
22560 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
22570 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
22580 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
22590 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
225a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
225b0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
225c0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
225d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
225e0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
225f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22600 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
22610 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
22620 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
22630 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
22640 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
22650 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
22660 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
22670 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
22680 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
22690 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
226a0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
226b0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
226c0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
226d0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
226e0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
226f0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
22700 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
22710 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
22720 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
22730 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
22740 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
22750 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
22760 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
22770 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
22780 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
22790 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
227a0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
227b0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
227c0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
227d0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
227e0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
227f0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
22800 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
22810 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
22820 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
22830 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
22840 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22850 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
22860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
22870 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
22880 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
22890 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
228a0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
228b0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
228c0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
228d0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
228e0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
228f0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
22900 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
22910 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
22920 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
22930 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
22940 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
22950 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
22960 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
22970 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
22980 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
22990 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
229a0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
229b0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
229c0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
229d0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
229e0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
229f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
22a00 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
22a10 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
22a20 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
22a30 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
22a40 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
22a50 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
22a60 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
22a70 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
22a80 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
22a90 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
22aa0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
22ab0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
22ac0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
22ad0 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
22ae0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
22af0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
22b00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
22b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b20 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
22b30 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
22b40 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
22b50 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
22b60 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
22b70 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
22b80 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
22b90 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
22ba0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
22bb0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
22bc0 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
22bd0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
22be0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
22bf0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
22c00 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
22c10 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
22c20 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
22c30 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
22c40 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
22c50 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
22c60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22c70 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
22c80 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
22c90 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
22ca0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
22cb0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
22cc0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
22cd0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
22ce0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
22cf0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
22d00 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
22d10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
22d20 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
22d30 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
22d40 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
22d50 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
22d60 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
22d70 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
22d80 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
22d90 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
22da0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
22db0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
22dc0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
22dd0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
22de0 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
22df0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
22e00 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
22e10 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
22e20 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
22e30 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
22e40 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
22e50 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
22e60 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
22e70 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
22e80 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
22e90 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
22ea0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
22eb0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
22ec0 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
22ed0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
22ee0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
22ef0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
22f00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
22f10 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
22f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
22f30 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
22f40 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
22f50 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
22f60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
22f70 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
22f80 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
22f90 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
22fa0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
22fb0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
22fc0 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
22fd0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
22fe0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
22ff0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
23000 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
23010 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
23020 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
23030 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
23040 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
23050 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
23060 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
23070 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
23080 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
23090 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
230a0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
230b0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
230c0 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
230d0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
230e0 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
230f0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
23100 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
23110 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
23120 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
23130 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
23140 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
23150 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
23160 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
23170 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
23180 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
23190 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
231a0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
231b0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
231c0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
231d0 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
231e0 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
231f0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
23200 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
23210 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
23220 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
23230 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
23240 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
23250 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
23260 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
23270 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
23280 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
23290 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
232a0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
232b0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
232c0 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
232d0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
232e0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
232f0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
23300 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
23310 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
23320 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
23330 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
23340 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
23350 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
23360 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
23370 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
23380 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
23390 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
233a0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
233b0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
233c0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
233d0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
233e0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
233f0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
23400 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
23410 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
23420 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
23430 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
23440 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
23450 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
23460 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
23470 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
23480 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
23490 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
234a0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
234b0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
234c0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
234d0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
234e0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
234f0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
23500 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
23510 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
23520 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23530 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
23540 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
23550 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
23560 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
23570 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
23580 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
23590 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
235a0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
235b0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
235c0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
235d0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
235e0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
235f0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
23600 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
23610 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
23620 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
23630 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
23640 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
23650 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
23660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23670 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
23680 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
23690 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
236a0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
236b0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
236c0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
236d0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
236e0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
236f0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
23700 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
23710 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
23720 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
23730 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
23740 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
23750 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
23760 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
23770 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
23780 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23790 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
237a0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
237b0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
237c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
237d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
237e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
237f0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
23800 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23810 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
23820 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
23830 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
23840 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
23850 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23860 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
23870 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23880 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
23890 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
238a0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
238b0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
238c0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
238d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
238e0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
238f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23900 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
23910 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23920 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
23930 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
23940 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
23950 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
23960 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
23970 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
23980 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
23990 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
239a0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
239b0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
239c0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
239d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
239e0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
239f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23a00 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
23a10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23a20 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
23a30 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
23a40 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
23a50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23a60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
23a70 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
23a80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23a90 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
23aa0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
23ab0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
23ac0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
23ad0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
23ae0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
23af0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23b00 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
23b10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23b20 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
23b30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23b40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
23b50 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
23b60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
23b70 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
23b80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
23b90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
23ba0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
23bb0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
23bc0 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
23bd0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
23be0 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
23bf0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
23c00 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
23c10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23c20 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
23c30 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
23c40 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
23c50 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
23c60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
23c70 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
23c80 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
23c90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23ca0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
23cb0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
23cc0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
23cd0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
23ce0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23cf0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
23d00 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
23d10 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
23d20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
23d30 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
23d40 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
23d50 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
23d60 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
23d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23d80 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
23d90 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
23da0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
23db0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
23dc0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
23dd0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23de0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
23df0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
23e00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23e10 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
23e20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23e30 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
23e40 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
23e50 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
23e60 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
23e70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23e80 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
23e90 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
23ea0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
23eb0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
23ec0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
23ed0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
23ee0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
23ef0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
23f00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23f10 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
23f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23f30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
23f40 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
23f50 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
23f60 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
23f70 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
23f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23f90 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
23fa0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
23fb0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
23fc0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
23fd0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
23fe0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
23ff0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
24000 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
24010 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
24020 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
24030 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24040 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
24050 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
24060 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
24070 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
24080 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
24090 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
240a0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
240b0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
240c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
240d0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
240e0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
240f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24100 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
24110 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
24120 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
24130 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
24140 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
24150 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
24160 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
24170 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
24180 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
24190 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
241a0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
241b0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
241c0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
241d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
241e0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
241f0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
24200 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
24210 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
24220 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
24230 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
24240 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24250 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
24260 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
24270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
24280 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
24290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
242a0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
242b0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
242c0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
242d0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
242e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
242f0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
24300 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
24310 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
24320 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
24330 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
24340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24350 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
24360 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
24370 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
24380 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
24390 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
243a0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
243b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
243c0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
243d0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
243e0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
243f0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
24400 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
24410 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
24420 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
24430 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
24440 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
24450 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
24460 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
24470 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
24480 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
24490 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
244a0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
244b0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
244c0 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
244d0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
244e0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
244f0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
24500 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
24510 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
24520 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
24530 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
24540 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
24550 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
24560 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
24570 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
24580 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
24590 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
245a0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
245b0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
245c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
245d0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
245e0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
245f0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
24600 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
24610 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
24620 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
24630 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
24640 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
24650 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
24660 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
24670 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
24680 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
24690 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
246a0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
246b0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
246c0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
246d0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
246e0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
246f0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
24700 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
24710 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
24720 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
24730 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
24740 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
24750 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
24760 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
24770 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
24780 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
24790 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
247a0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
247b0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
247c0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
247d0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
247e0 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
247f0 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
24800 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
24810 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
24820 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
24830 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
24840 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
24850 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
24860 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
24870 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
24880 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
24890 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
248a0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
248b0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
248c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
248d0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
248e0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
248f0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
24900 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
24910 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
24920 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
24930 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
24940 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
24950 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
24960 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
24970 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
24980 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
24990 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
249a0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
249b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
249c0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
249d0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
249e0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
249f0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
24a00 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
24a10 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
24a20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
24a30 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
24a40 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
24a50 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
24a60 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24a70 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
24a80 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
24a90 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
24aa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
24ab0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
24ac0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
24ad0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
24ae0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
24af0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
24b00 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
24b10 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
24b20 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
24b30 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
24b40 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
24b50 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
24b60 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
24b70 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
24b80 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
24b90 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
24ba0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
24bb0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
24bc0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
24bd0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
24be0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
24bf0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
24c00 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
24c10 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
24c20 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
24c30 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
24c40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
24c50 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
24c60 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
24c70 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
24c80 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
24c90 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
24ca0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
24cb0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
24cc0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
24cd0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
24ce0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
24cf0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
24d00 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
24d10 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
24d20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
24d30 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
24d40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
24d50 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
24d60 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
24d70 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
24d80 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
24d90 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
24da0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
24db0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
24dc0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
24dd0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
24de0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
24df0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
24e00 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
24e10 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
24e20 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
24e30 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
24e40 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
24e50 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
24e60 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
24e70 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
24e80 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
24e90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
24ea0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
24eb0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
24ec0 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
24ed0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
24ee0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
24ef0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
24f00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24f10 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
24f20 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
24f30 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
24f40 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
24f50 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
24f60 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
24f70 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
24f80 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
24f90 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
24fa0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
24fb0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
24fc0 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
24fd0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
24fe0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
24ff0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
25000 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
25010 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
25020 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
25030 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
25040 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
25050 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
25060 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
25070 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
25080 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
25090 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
250a0 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
250b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
250c0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
250d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
250e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
250f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25100 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
25110 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25120 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
25130 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
25150 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25160 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
25170 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
25180 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
25190 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
251a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
251b0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
251c0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
251d0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
251e0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
251f0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
25200 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25210 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
25220 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
25230 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
25240 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
25250 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
25260 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
25270 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
25280 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
25290 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
252a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
252b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
252c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
252d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
252e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
252f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25300 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
25310 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25320 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25330 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25340 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
25350 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
25360 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
25370 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
25380 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
25390 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
253a0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
253b0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
253c0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
253d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
253e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
253f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
25400 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
25410 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
25420 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
25430 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
25440 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
25450 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
25460 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
25470 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
25480 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
25490 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
254a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
254b0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
254c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
254d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
254e0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
254f0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
25500 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
25510 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
25520 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
25530 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
25540 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
25550 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
25560 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
25570 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
25580 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
25590 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
255a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
255b0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
255c0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
255d0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
255e0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
255f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
25600 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
25610 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
25620 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
25630 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
25640 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
25650 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
25660 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
25670 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
25680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25690 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
256a0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
256b0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
256c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
256d0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
256e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
256f0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
25700 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
25710 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
25720 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
25730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25740 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
25750 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
25760 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
25770 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
25780 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25790 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
257a0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
257b0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
257c0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
257d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
257e0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
257f0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
25800 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
25810 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
25820 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
25830 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
25840 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25850 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
25860 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
25870 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
25880 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
25890 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
258a0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
258b0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
258c0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
258d0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
258e0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
258f0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
25900 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
25910 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
25920 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
25930 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
25940 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
25950 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
25960 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
25970 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
25980 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
25990 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
259a0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
259b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
259c0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
259d0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
259e0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
259f0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
25a00 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
25a10 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
25a20 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
25a30 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
25a40 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
25a50 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
25a60 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
25a70 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
25a80 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
25a90 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
25aa0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
25ab0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
25ac0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
25ad0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
25ae0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
25af0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
25b00 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
25b10 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
25b20 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
25b30 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
25b40 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
25b50 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
25b60 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
25b70 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
25b80 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
25b90 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
25ba0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
25bb0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
25bc0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
25bd0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
25be0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
25bf0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
25c00 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
25c10 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
25c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25c30 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
25c40 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
25c50 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
25c60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
25c70 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
25c80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
25c90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
25ca0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
25cb0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
25cc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
25cd0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
25ce0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
25cf0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
25d00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
25d10 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
25d20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25d30 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
25d40 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
25d50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25d60 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
25d70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
25d80 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
25d90 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
25da0 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
25db0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
25dc0 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
25dd0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
25de0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25df0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
25e00 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
25e10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25e20 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
25e30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
25e40 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
25e50 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
25e60 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
25e70 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
25e80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25e90 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
25ea0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
25eb0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
25ec0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
25ed0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
25ee0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
25ef0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
25f00 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
25f10 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
25f20 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
25f30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25f40 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
25f50 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
25f60 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
25f70 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
25f80 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
25f90 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
25fa0 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
25fb0 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
25fc0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
25fd0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
25fe0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
25ff0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
26000 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
26010 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
26020 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
26030 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
26040 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
26050 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
26060 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
26070 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
26080 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
26090 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
260a0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
260b0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
260c0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
260d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
260e0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
260f0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
26100 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
26110 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
26120 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
26130 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
26140 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
26150 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
26160 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
26170 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
26180 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
26190 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
261a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
261b0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
261c0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
261d0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
261e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
261f0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
26200 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
26210 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
26220 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
26230 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
26240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
26250 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
26260 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
26270 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
26280 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
26290 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
262a0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
262b0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
262c0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
262d0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
262e0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
262f0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
26300 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
26310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
26320 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
26330 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
26340 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
26350 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
26360 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
26370 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
26380 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
26390 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
263a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
263b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
263c0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
263d0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
263e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
263f0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
26400 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
26410 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
26420 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
26430 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
26440 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
26450 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
26460 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
26470 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
26480 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
26490 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
264a0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
264b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
264c0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
264d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
264e0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
264f0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
26500 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
26510 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
26520 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
26530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26540 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
26550 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
26560 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
26570 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
26580 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
26590 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
265a0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
265b0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
265c0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
265d0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
265e0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
265f0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
26600 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26610 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
26620 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
26630 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
26640 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26650 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
26660 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
26670 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
26680 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
26690 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
266a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
266b0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
266c0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
266d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
266e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
266f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26700 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
26710 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
26720 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26730 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
26740 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
26750 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
26760 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
26770 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
26780 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
26790 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
267a0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
267b0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
267c0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
267d0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
267e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
267f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
26800 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
26810 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
26820 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
26830 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
26840 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
26850 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
26860 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
26870 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
26880 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
26890 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
268a0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
268b0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
268c0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
268d0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
268e0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
268f0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
26900 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
26910 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
26920 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
26930 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
26940 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
26950 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
26960 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
26970 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
26980 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
26990 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
269a0 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
269b0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
269c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
269d0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
269e0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
269f0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
26a00 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
26a10 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
26a20 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
26a30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
26a40 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
26a50 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
26a60 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
26a70 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
26a80 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
26a90 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
26aa0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
26ab0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
26ac0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
26ad0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
26ae0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
26af0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
26b00 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
26b10 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
26b20 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
26b30 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
26b40 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
26b50 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
26b60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
26b70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
26b80 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
26b90 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
26ba0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
26bb0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
26bc0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
26bd0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
26be0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
26bf0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
26c00 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
26c10 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
26c20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
26c30 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
26c40 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
26c50 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
26c60 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
26c70 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
26c80 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
26c90 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
26ca0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
26cb0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
26cc0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
26cd0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
26ce0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
26cf0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
26d00 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
26d10 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
26d20 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
26d30 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
26d40 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
26d50 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
26d60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
26d70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26d80 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
26d90 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
26da0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
26db0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
26dc0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
26dd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26de0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
26df0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
26e00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
26e10 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
26e20 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
26e30 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
26e40 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
26e50 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
26e60 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
26e70 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
26e80 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
26e90 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
26ea0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
26eb0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
26ec0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
26ed0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
26ee0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
26ef0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
26f00 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
26f10 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
26f20 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
26f30 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
26f40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
26f50 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
26f60 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
26f70 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
26f80 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
26f90 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
26fa0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
26fb0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
26fc0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
26fd0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
26fe0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
26ff0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
27000 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
27010 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
27020 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
27030 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
27040 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
27050 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
27060 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
27070 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
27080 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
27090 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
270a0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
270b0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
270c0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
270d0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
270e0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
270f0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
27100 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
27110 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
27120 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
27130 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
27140 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
27150 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
27160 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27170 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
27180 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
27190 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
271a0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
271b0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
271c0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
271d0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
271e0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
271f0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
27200 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27210 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
27220 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
27230 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
27240 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
27250 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
27260 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
27270 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
27280 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
27290 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
272a0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
272b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
272c0 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
272d0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
272e0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
272f0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
27300 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
27310 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
27320 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
27330 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
27340 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
27350 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
27360 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
27370 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
27380 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
27390 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
273a0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
273b0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
273c0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
273d0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
273e0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
273f0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
27400 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
27410 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
27420 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27430 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
27440 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
27450 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
27460 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
27470 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
27480 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
27490 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
274a0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
274b0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
274c0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
274d0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
274e0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
274f0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
27500 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
27510 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
27520 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
27530 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
27540 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27550 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
27560 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
27570 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
27580 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
27590 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
275a0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
275b0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
275c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
275d0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
275e0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
275f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
27600 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
27610 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
27620 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
27630 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
27640 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
27650 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
27660 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
27670 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
27680 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
27690 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
276a0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
276b0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
276c0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
276d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
276e0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
276f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27700 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
27710 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
27720 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
27730 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
27740 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
27750 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
27760 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
27770 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
27780 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
27790 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
277a0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
277b0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
277c0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
277d0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
277e0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
277f0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
27800 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
27810 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
27820 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
27830 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
27840 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
27850 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
27860 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
27870 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
27880 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
27890 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
278a0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
278b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
278c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
278d0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
278e0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
278f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
27900 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
27910 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
27920 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
27930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
27940 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
27950 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
27960 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
27970 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
27980 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
27990 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
279a0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
279b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
279c0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
279d0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
279e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
279f0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
27a00 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
27a10 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
27a20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
27a30 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
27a40 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
27a50 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
27a60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
27a70 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
27a80 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
27a90 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
27aa0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
27ab0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27ac0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
27ad0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
27ae0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
27af0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
27b00 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
27b10 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
27b20 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
27b30 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
27b40 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
27b50 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
27b60 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
27b70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
27b80 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
27b90 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
27ba0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27bb0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
27bc0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
27bd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
27be0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
27bf0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27c00 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
27c10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27c20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27c30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27c40 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
27c50 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
27c60 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
27c70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27c80 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
27c90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27ca0 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
27cb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27cc0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
27cd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
27ce0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
27cf0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27d00 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
27d10 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
27d20 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
27d30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27d40 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
27d50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
27d60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27d70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27d80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27d90 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
27da0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
27db0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
27dc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27dd0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
27de0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27df0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
27e00 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
27e10 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
27e20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27e30 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
27e40 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
27e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27e60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27e70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
27e80 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
27e90 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
27ea0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27eb0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
27ec0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
27ed0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
27ee0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
27ef0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
27f00 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
27f10 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
27f20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27f30 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
27f40 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
27f50 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
27f60 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
27f70 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
27f80 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
27f90 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
27fa0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
27fb0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
27fc0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
27fd0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
27fe0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
27ff0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
28000 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
28010 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
28020 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
28030 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
28040 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
28050 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
28060 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
28070 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
28080 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
28090 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
280a0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
280b0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
280c0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
280d0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
280e0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
280f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
28100 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
28110 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
28120 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
28130 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28140 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
28150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28160 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28170 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
28180 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
28190 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
281a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
281b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
281c0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
281d0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
281e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
281f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28200 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
28210 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
28220 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
28230 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
28240 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
28250 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28260 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
28270 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
28280 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
28290 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
282a0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
282b0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
282c0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
282d0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
282e0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
282f0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
28300 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
28310 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
28320 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
28330 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
28340 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
28350 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
28360 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
28370 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
28380 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
28390 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
283a0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
283b0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
283c0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
283d0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
283e0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
283f0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
28400 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
28410 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
28420 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
28430 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
28440 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
28450 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
28460 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
28470 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
28480 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
28490 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
284a0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
284b0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
284c0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
284d0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
284e0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
284f0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
28500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28510 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
28520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28530 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
28540 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28550 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
28560 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
28570 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28580 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
28590 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
285a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
285b0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
285c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
285d0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
285e0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
285f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28600 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28610 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
28620 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
28630 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
28640 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
28650 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
28660 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
28670 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
28680 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
28690 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
286a0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
286b0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
286c0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
286d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
286e0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
286f0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
28700 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
28710 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
28720 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
28730 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
28740 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
28750 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
28760 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
28770 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
28780 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
28790 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
287a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
287b0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
287c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
287d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
287e0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
287f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28800 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
28810 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
28820 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
28830 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
28840 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28850 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28860 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
28870 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
28880 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
28890 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
288a0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
288b0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
288c0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
288d0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
288e0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
288f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28900 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
28910 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
28920 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
28930 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
28940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28950 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
28960 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
28970 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
28980 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
28990 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
289a0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
289b0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
289c0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
289d0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
289e0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
289f0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
28a00 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
28a10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28a20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
28a30 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
28a40 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
28a50 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
28a60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
28a70 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
28a80 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
28a90 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
28aa0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
28ab0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
28ac0 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
28ad0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
28ae0 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
28af0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28b00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
28b10 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
28b20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
28b30 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
28b40 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
28b50 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
28b60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
28b70 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
28b80 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
28b90 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
28ba0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
28bb0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
28bc0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
28bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28be0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
28bf0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
28c00 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
28c10 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
28c20 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
28c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
28c40 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
28c50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
28c60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
28c70 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
28c80 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
28c90 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
28ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28cb0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
28cc0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
28cd0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
28ce0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
28cf0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
28d00 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
28d10 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
28d20 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
28d30 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
28d40 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
28d50 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
28d60 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
28d70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28d80 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
28d90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
28da0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
28db0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
28dc0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
28dd0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
28de0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
28df0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
28e00 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
28e10 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
28e20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
28e30 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
28e40 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
28e50 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
28e60 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
28e70 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
28e80 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
28e90 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
28ea0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
28eb0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
28ec0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
28ed0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
28ee0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
28ef0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
28f00 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
28f10 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
28f20 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
28f30 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
28f40 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
28f50 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
28f60 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
28f70 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
28f80 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
28f90 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
28fa0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
28fb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
28fc0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
28fd0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
28fe0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
28ff0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
29000 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
29010 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49  he next..*/.SQLI
29020 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
29030 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29040 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
29050 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
29060 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
29070 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29080 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
29090 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
290a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
290b0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
290c0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
290d0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
290e0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
290f0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
29100 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
29110 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
29120 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
29130 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
29140 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
29150 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
29160 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
29170 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
29180 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
29190 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
291a0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
291b0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
291c0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
291d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
291e0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
291f0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
29200 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
29210 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
29220 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
29230 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
29240 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
29250 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
29260 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
29270 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
29280 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
29290 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
292a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
292b0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
292c0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
292d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
292e0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
292f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
29300 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
29310 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
29320 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
29330 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29340 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
29350 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
29360 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
29370 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
29380 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
29390 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
293a0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
293b0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
293c0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
293d0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
293e0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
293f0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
29400 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
29410 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29420 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
29430 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
29440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29450 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
29460 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
29470 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
29480 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
29490 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
294a0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
294b0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
294c0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
294d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
294e0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
294f0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
29500 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
29510 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
29520 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
29530 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
29540 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
29550 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
29560 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
29570 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
29580 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
29590 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
295a0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
295b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
295c0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
295d0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
295e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
295f0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
29600 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
29610 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
29620 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
29630 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
29640 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
29650 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
29660 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
29670 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
29680 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
29690 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
296a0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
296b0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
296c0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
296d0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
296e0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
296f0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
29700 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
29710 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
29720 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
29730 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
29740 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
29750 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
29760 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
29770 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
29780 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
29790 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
297a0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
297b0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
297c0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
297d0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
297e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
297f0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
29800 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
29810 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
29820 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
29830 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
29840 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
29850 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
29860 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29870 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
29880 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
29890 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
298a0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
298b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
298c0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
298d0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
298e0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
298f0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
29900 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
29910 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
29920 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29930 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
29940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
29950 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
29960 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29970 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
29980 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
29990 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
299a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
299b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
299c0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
299d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
299e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
299f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29a00 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
29a10 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
29a20 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
29a30 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
29a40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29a50 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
29a60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
29a70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29a80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29a90 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
29aa0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
29ab0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
29ac0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
29ad0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
29ae0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
29af0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
29b00 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
29b10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29b20 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
29b30 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
29b40 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
29b50 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
29b60 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
29b70 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
29b80 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
29b90 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
29ba0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
29bb0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
29bc0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
29bd0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
29be0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
29bf0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
29c00 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
29c10 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
29c20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
29c30 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
29c40 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
29c50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
29c60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
29c70 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
29c80 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
29c90 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
29ca0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
29cb0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
29cc0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
29cd0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
29ce0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
29cf0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
29d00 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
29d10 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
29d20 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
29d30 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
29d40 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
29d50 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
29d60 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
29d70 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
29d80 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
29d90 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
29da0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
29db0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
29dc0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
29dd0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
29de0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
29df0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
29e00 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
29e10 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
29e20 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
29e30 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
29e40 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
29e50 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
29e60 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
29e70 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
29e80 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
29e90 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
29ea0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
29eb0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
29ec0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
29ed0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
29ee0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
29ef0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
29f00 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
29f10 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
29f20 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
29f30 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
29f40 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ues..*/.SQLITE_A
29f50 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
29f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
29f70 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
29f80 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
29f90 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
29fa0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29fb0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
29fc0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
29fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29fe0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
29ff0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2a000 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2a010 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2a020 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2a030 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2a040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a050 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2a060 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a070 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2a080 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a090 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2a0a0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2a0b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a0c0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2a0d0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2a0e0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2a0f0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2a100 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2a110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2a120 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2a130 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2a140 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2a150 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2a160 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2a170 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2a180 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2a190 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2a1a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2a1b0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2a1c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a1d0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2a1e0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2a1f0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2a200 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2a210 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2a220 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2a230 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2a240 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2a250 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2a260 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2a270 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2a280 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2a290 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2a2a0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2a2b0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2a2c0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2a2d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2a2e0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2a2f0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2a300 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2a310 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2a320 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2a330 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a340 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2a350 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2a360 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2a370 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2a380 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2a390 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2a3a0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2a3b0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2a3c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2a3d0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2a3e0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2a3f0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2a400 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2a410 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2a420 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2a430 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2a440 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2a450 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2a460 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2a470 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2a480 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2a490 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2a4a0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2a4b0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2a4c0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2a4d0 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2a4e0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2a4f0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2a500 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2a510 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2a520 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2a530 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2a540 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2a550 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2a560 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2a570 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2a580 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2a590 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2a5a0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2a5b0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2a5c0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2a5d0 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2a5e0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2a5f0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2a600 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2a610 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2a620 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2a630 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2a640 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a650 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2a660 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2a670 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2a680 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2a690 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2a6a0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2a6b0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2a6c0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2a6d0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2a6e0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2a6f0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2a700 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2a710 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2a720 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2a730 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2a740 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2a750 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2a760 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2a770 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2a780 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2a790 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2a7a0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2a7b0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2a7c0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2a7d0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2a7e0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2a7f0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2a800 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2a810 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2a820 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2a830 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2a840 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2a850 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2a860 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2a870 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2a880 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2a890 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2a8a0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2a8b0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2a8c0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2a8d0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2a8e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2a8f0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2a900 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a910 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2a920 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2a930 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2a940 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2a950 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2a960 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2a970 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2a980 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2a990 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2a9a0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2a9b0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2a9c0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2a9d0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2a9e0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2a9f0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2aa00 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2aa10 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2aa20 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2aa30 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2aa40 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2aa50 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2aa60 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2aa70 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2aa80 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2aa90 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2aaa0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2aab0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2aac0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2aad0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2aae0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2aaf0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2ab00 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2ab10 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2ab20 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2ab30 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2ab40 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2ab50 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2ab60 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2ab70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2ab80 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2ab90 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2aba0 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2abb0 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2abc0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2abd0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2abe0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2abf0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2ac00 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2ac10 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2ac20 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2ac30 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2ac40 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2ac50 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2ac60 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2ac70 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2ac80 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2ac90 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2aca0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2acb0 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2acc0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2acd0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2ace0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2acf0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2ad00 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2ad10 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2ad20 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2ad30 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2ad40 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2ad50 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2ad60 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2ad70 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2ad80 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2ad90 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2ada0 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2adb0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2adc0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2add0 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2ade0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2adf0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2ae00 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2ae10 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2ae20 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2ae30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2ae40 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2ae50 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2ae60 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2ae70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2ae80 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2ae90 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2aea0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2aeb0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2aec0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2aed0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2aee0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2aef0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2af00 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2af10 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2af20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2af30 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2af40 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2af50 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2af60 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2af70 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2af80 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2af90 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2afa0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2afb0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2afc0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2afd0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2afe0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2aff0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2b000 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2b010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b020 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2b030 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2b040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b050 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b060 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2b070 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2b080 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2b090 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2b0a0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2b0b0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2b0c0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2b0d0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2b0e0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2b0f0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2b100 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2b110 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2b120 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2b140 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2b150 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2b160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b170 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2b180 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b190 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b1a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2b1b0 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2b1c0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b1d0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2b1e0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2b1f0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2b200 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2b210 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2b220 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2b230 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2b240 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2b250 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2b260 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2b270 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2b280 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2b290 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2b2a0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2b2b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b2c0 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
2b2d0 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
2b2e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2b2f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b300 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2b310 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2b320 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
2b330 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2b340 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2b350 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
2b360 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
2b370 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b380 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2b390 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
2b3a0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
2b3b0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2b3c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2b3d0 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
2b3e0 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2b3f0 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
2b400 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
2b410 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
2b420 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
2b430 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
2b440 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
2b450 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
2b460 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
2b470 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
2b480 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2b490 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2b4a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2b4b0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2b4c0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2b4d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2b4e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2b4f0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2b500 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2b510 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2b520 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2b530 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2b540 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2b550 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2b560 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2b570 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2b580 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2b590 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2b5a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2b5b0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2b5c0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2b5d0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2b5e0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2b5f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2b600 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2b610 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2b620 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2b630 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2b640 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2b650 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2b660 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2b670 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2b680 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2b690 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2b6a0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2b6b0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2b6c0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2b6d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2b6e0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2b6f0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2b700 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2b710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2b720 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2b730 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2b740 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2b750 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2b760 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2b770 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2b780 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2b790 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2b7a0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2b7b0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2b7c0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2b7d0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2b7e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b7f0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2b800 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2b810 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2b820 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2b830 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2b840 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2b850 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2b860 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2b870 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2b880 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2b890 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2b8a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2b8b0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2b8c0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2b8d0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2b8e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2b8f0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2b900 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2b910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b920 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2b930 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2b940 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2b950 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2b960 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2b970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2b980 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2b990 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2b9a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2b9b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2b9c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2b9d0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2b9e0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2b9f0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2ba00 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2ba10 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2ba20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2ba30 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2ba40 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2ba50 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2ba60 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2ba70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2ba80 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2ba90 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2baa0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2bab0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2bac0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2bad0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2bae0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2baf0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2bb00 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2bb10 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2bb20 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2bb30 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2bb40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2bb50 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2bb60 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2bb70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2bb80 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2bb90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2bba0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2bbb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2bbc0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2bbd0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2bbe0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2bbf0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2bc00 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2bc10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2bc20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2bc30 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2bc40 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2bc50 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2bc60 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2bc70 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2bc80 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2bc90 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2bca0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2bcb0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2bcc0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2bcd0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2bce0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2bcf0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2bd00 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2bd10 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2bd20 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2bd30 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2bd40 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2bd50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2bd60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2bd70 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2bd80 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2bd90 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2bda0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2bdb0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2bdc0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2bdd0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2bde0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2bdf0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2be00 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2be10 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2be20 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2be30 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2be40 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2be50 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2be60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2be70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2be80 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2be90 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2bea0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2beb0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2bec0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2bed0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2bee0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2bef0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2bf00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2bf10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2bf20 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2bf30 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2bf40 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2bf50 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2bf60 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2bf70 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2bf80 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2bf90 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2bfa0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2bfb0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2bfc0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2bfd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2bfe0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2bff0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2c000 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2c010 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2c020 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2c030 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2c040 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2c050 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c060 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2c070 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2c080 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2c090 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2c0a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c0b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2c0c0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2c0d0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2c0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c0f0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2c100 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2c110 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2c120 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2c130 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2c140 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2c150 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c160 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2c170 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c180 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2c190 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c1a0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2c1b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2c1c0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2c1d0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2c1e0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2c1f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c200 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2c210 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2c220 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2c230 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2c240 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c250 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2c260 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2c270 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c280 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2c290 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2c2a0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2c2b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2c2c0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2c2d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c2e0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2c2f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c300 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2c310 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2c320 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2c330 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2c340 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2c350 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2c360 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2c370 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2c380 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2c390 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2c3a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2c3b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2c3c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2c3d0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2c3e0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2c3f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c400 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2c410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c420 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2c430 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2c440 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2c450 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2c460 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2c470 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2c480 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2c490 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c4a0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2c4b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c4c0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2c4d0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2c4e0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2c4f0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2c500 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2c510 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2c520 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c540 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2c550 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2c560 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2c570 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2c580 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2c590 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2c5a0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2c5b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2c5c0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2c5d0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2c5e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2c5f0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2c600 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2c610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2c620 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2c630 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c640 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c650 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2c660 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2c670 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2c680 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2c690 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2c6a0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2c6b0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2c6c0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2c6d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c6e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c6f0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2c700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c710 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2c720 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2c730 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2c740 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2c750 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2c760 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2c770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c780 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2c790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2c7a0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2c7b0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2c7c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2c7d0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2c7e0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2c7f0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2c800 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2c810 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2c820 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2c830 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2c840 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2c850 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2c860 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2c870 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2c880 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2c890 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2c8a0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2c8b0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2c8c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2c8d0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2c8e0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2c8f0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2c900 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2c910 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2c920 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2c930 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2c940 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2c950 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2c960 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2c970 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2c980 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2c990 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2c9a0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2c9b0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2c9c0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2c9d0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2c9e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2c9f0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2ca00 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2ca10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2ca20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2ca30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2ca40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2ca50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2ca60 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2ca70 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2ca80 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2ca90 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2caa0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2cab0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2cac0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2cad0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2cae0 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2caf0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2cb00 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2cb10 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2cb20 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2cb30 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2cb40 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2cb50 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2cb60 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2cb70 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2cb80 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2cb90 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2cba0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2cbb0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2cbc0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2cbd0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2cbe0 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2cbf0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2cc00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2cc10 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2cc20 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2cc30 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2cc40 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2cc50 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2cc60 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2cc70 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2cc80 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2cc90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2cca0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2ccb0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2ccc0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2ccd0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2cce0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2ccf0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2cd00 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2cd10 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2cd20 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2cd30 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2cd40 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2cd50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2cd60 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2cd70 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2cd80 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2cd90 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2cda0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2cdb0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2cdc0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2cdd0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2cde0 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2cdf0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2ce00 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2ce10 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2ce20 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2ce30 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2ce40 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2ce50 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2ce60 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2ce70 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2ce80 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2ce90 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2cea0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2ceb0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2cec0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2ced0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2cee0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2cef0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2cf00 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2cf10 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2cf20 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2cf30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2cf40 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2cf50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2cf60 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2cf70 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2cf80 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2cf90 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2cfa0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2cfb0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2cfc0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2cfd0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2cfe0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2cff0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2d000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d010 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2d020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d030 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2d040 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2d050 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2d060 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2d070 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2d080 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2d090 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2d0a0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2d0b0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2d0c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d0d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2d0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2d0f0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2d100 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2d110 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2d120 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2d130 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2d140 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2d150 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2d160 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2d170 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2d180 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2d190 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2d1a0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2d1b0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2d1c0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2d1d0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2d1e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2d1f0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2d200 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2d210 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2d220 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2d230 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2d240 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2d250 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2d260 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2d270 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2d280 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2d290 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2d2a0 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2d2b0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2d2c0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2d2d0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2d2e0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2d2f0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2d300 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2d310 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2d320 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2d330 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2d340 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2d350 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2d360 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2d370 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2d380 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2d390 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2d3a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2d3b0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2d3c0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2d3d0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2d3e0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2d3f0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2d400 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d410 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2d420 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2d430 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2d440 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2d450 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d460 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2d470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d480 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2d490 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2d4a0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2d4b0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2d4c0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2d4d0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2d4e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d4f0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2d500 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2d510 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2d520 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2d530 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2d540 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2d550 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2d560 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2d570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d580 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2d590 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d5a0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2d5b0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2d5c0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2d5d0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2d5e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2d5f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2d600 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2d610 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2d620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d630 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2d640 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2d650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d660 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2d670 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2d680 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2d690 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2d6a0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2d6b0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2d6c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2d6d0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2d6e0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2d6f0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2d700 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2d710 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2d720 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d730 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2d740 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2d750 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2d760 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2d770 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2d780 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2d790 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2d7a0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2d7b0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2d7c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2d7d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2d7e0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2d7f0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2d800 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2d810 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2d820 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2d830 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2d840 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2d850 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2d860 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2d870 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2d880 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2d890 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2d8a0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2d8b0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2d8c0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2d8d0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2d8e0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2d8f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2d900 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2d910 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2d920 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2d930 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  M].)^.*/.SQLITE_
2d940 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2d950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d960 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2d970 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2d980 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2d990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d9a0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2d9b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2d9c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2d9d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d9e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d9f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2da00 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
2da10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2da20 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2da30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2da40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2da50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2da60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2da70 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2da80 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
2da90 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2daa0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2dab0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2dac0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2dad0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2dae0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2daf0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2db00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2db10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2db20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2db30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2db40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2db50 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2db60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2db70 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2db80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2db90 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2dba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2dbb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2dbc0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2dbd0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2dbe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2dbf0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2dc00 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2dc10 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2dc20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2dc30 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2dc40 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
2dc50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dc60 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
2dc70 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2dc80 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
2dc90 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
2dca0 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
2dcb0 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
2dcc0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
2dcd0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
2dce0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
2dcf0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
2dd00 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
2dd10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2dd20 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
2dd30 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
2dd40 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
2dd50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2dd60 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
2dd70 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2dd80 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
2dd90 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
2dda0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ddb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2ddc0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2ddd0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2dde0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
2ddf0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
2de00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2de10 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
2de20 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
2de30 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
2de40 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
2de50 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
2de60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2de70 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
2de80 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
2de90 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
2dea0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2deb0 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
2dec0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
2ded0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
2dee0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
2def0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2df00 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
2df10 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
2df20 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
2df30 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2df40 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
2df50 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
2df60 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
2df70 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
2df80 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
2df90 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
2dfa0 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
2dfb0 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
2dfc0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
2dfd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2dfe0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2dff0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
2e000 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
2e010 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2e020 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2e030 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
2e040 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
2e050 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
2e060 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
2e070 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
2e080 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
2e090 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  ruption..*/.SQLI
2e0a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e0b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
2e0c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2e0d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e0e0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
2e0f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2e100 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
2e110 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
2e120 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2e130 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
2e140 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e150 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
2e160 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2e170 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
2e180 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
2e190 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
2e1a0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
2e1b0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
2e1c0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
2e1d0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
2e1e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2e1f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2e200 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
2e210 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
2e220 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
2e230 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
2e240 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
2e250 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
2e260 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2e270 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
2e280 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
2e290 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
2e2a0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
2e2b0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
2e2c0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
2e2d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2e2e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2e2f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2e300 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2e310 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
2e320 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2e330 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
2e340 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
2e350 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2e360 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
2e370 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2e380 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
2e390 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2e3a0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2e3b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
2e3c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2e3d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2e3e0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2e3f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2e400 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
2e410 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
2e420 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
2e430 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2e440 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
2e450 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2e460 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2e470 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2e480 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
2e490 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
2e4a0 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
2e4b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
2e4c0 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
2e4d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e4e0 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  t] S..*/.SQLITE_
2e4f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e500 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2e510 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2e520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2e530 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2e540 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
2e550 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2e560 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2e570 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2e580 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2e590 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2e5a0 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2e5b0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2e5c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2e5d0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
2e5e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2e5f0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2e600 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2e610 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2e620 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2e630 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2e640 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2e650 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2e660 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2e670 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2e680 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2e690 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2e6a0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2e6b0 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
2e6c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2e6d0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2e6e0 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
2e6f0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
2e700 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
2e710 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2e720 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
2e730 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
2e740 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
2e750 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
2e760 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
2e770 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2e780 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
2e790 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
2e7a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2e7b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e7c0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2e7d0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2e7e0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2e7f0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
2e800 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
2e810 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
2e820 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2e830 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
2e840 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e850 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
2e860 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
2e870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e880 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
2e890 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2e8a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2e8b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2e8c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2e8d0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2e8e0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
2e8f0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
2e900 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
2e910 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
2e920 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
2e930 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
2e940 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
2e950 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
2e960 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2e970 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
2e980 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
2e990 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
2e9a0 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
2e9b0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
2e9c0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
2e9d0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2e9e0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
2e9f0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
2ea00 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2ea10 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
2ea20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2ea30 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
2ea40 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
2ea50 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2ea60 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
2ea70 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2ea80 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
2ea90 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2eaa0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
2eab0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2eac0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2ead0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2eae0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
2eaf0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
2eb00 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
2eb10 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2eb20 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
2eb30 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
2eb40 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
2eb50 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
2eb60 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
2eb70 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
2eb80 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2eb90 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
2eba0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
2ebb0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
2ebc0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
2ebd0 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
2ebe0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
2ebf0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
2ec00 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
2ec10 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
2ec20 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
2ec30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2ec40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2ec50 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
2ec60 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
2ec70 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2ec80 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2ec90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2eca0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2ecb0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2ecc0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2ecd0 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
2ece0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
2ecf0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2ed00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ed10 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2ed20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ed30 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2ed40 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2ed50 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2ed60 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2ed70 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2ed80 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
2ed90 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2eda0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2edb0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
2edc0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
2edd0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
2ede0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
2edf0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2ee00 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
2ee10 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
2ee20 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
2ee30 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
2ee40 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
2ee50 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
2ee60 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
2ee70 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
2ee80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
2ee90 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
2eea0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
2eeb0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2eec0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
2eed0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
2eee0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2eef0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
2ef00 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
2ef10 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
2ef20 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
2ef30 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
2ef40 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
2ef50 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
2ef60 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
2ef70 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
2ef80 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
2ef90 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
2efa0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
2efb0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
2efc0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2efd0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2efe0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
2eff0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2f000 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2f010 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
2f020 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
2f030 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
2f040 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
2f050 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
2f060 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
2f070 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
2f080 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2f090 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2f0a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f0b0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2f0c0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2f0d0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
2f0e0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
2f0f0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
2f100 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2f110 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2f120 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2f130 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
2f140 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2f150 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
2f160 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
2f170 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
2f180 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f190 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
2f1a0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
2f1b0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
2f1c0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
2f1d0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2f1e0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
2f1f0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
2f200 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
2f210 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
2f220 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
2f230 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
2f240 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
2f250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2f260 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
2f270 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2f280 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
2f290 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
2f2a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f2b0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
2f2c0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
2f2d0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2f2e0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
2f2f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
2f300 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
2f310 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
2f320 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
2f330 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2f340 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2f350 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
2f360 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
2f370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2f380 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f390 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
2f3a0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
2f3b0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
2f3c0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2f3d0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2f3e0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
2f3f0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2f400 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
2f410 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
2f420 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
2f430 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
2f440 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
2f450 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
2f460 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2f470 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2f480 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
2f490 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2f4a0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2f4b0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2f4c0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
2f4d0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2f4e0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
2f4f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
2f500 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
2f510 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
2f520 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2f530 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f540 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
2f550 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
2f560 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2f570 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2f580 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
2f590 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
2f5a0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
2f5b0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
2f5c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2f5d0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2f5e0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
2f5f0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
2f600 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2f610 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2f620 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
2f630 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
2f640 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
2f650 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2f660 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2f670 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2f680 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
2f690 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
2f6a0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
2f6b0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
2f6c0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
2f6d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f6e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
2f6f0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
2f700 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f710 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
2f720 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
2f730 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
2f740 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
2f750 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
2f760 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
2f770 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2f780 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
2f790 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
2f7a0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2f7b0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
2f7c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2f7d0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
2f7e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f7f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f800 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2f810 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2f820 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2f830 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2f840 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2f850 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2f860 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2f870 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2f880 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2f890 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2f8a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f8b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2f8c0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2f8d0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2f8e0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
2f8f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f900 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f910 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2f920 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2f930 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2f940 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2f950 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2f960 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2f970 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2f980 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2f990 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2f9a0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2f9b0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2f9c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f9d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f9e0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2f9f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2fa00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2fa10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fa20 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
2fa30 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2fa40 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2fa50 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2fa60 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2fa70 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2fa80 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2fa90 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2faa0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2fab0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2fac0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2fad0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2fae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2faf0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2fb00 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fb10 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
2fb20 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2fb30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fb40 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
2fb50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2fb60 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
2fb70 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
2fb80 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
2fb90 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
2fba0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
2fbb0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
2fbc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fbd0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
2fbe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fbf0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
2fc00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fc10 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
2fc20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fc30 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
2fc40 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
2fc50 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
2fc60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
2fc70 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
2fc80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2fc90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
2fca0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
2fcb0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2fcc0 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
2fcd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2fce0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
2fcf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
2fd00 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
2fd10 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
2fd20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2fd30 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
2fd40 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
2fd50 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
2fd60 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2fd70 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
2fd80 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
2fd90 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
2fda0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
2fdb0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
2fdc0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
2fdd0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
2fde0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
2fdf0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2fe00 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
2fe10 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
2fe20 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
2fe30 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
2fe40 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
2fe50 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
2fe60 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
2fe70 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
2fe80 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
2fe90 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
2fea0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2feb0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2fec0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2fed0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
2fee0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2fef0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
2ff00 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2ff10 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
2ff20 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2ff30 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
2ff40 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
2ff50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ff60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2ff70 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ff80 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2ff90 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2ffa0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2ffb0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
2ffc0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
2ffd0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
2ffe0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
2fff0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
30000 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30010 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
30020 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
30030 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
30040 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
30050 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
30060 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
30070 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
30080 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
30090 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
300a0 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
300b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
300c0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
300d0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
300e0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
300f0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
30100 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
30110 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
30120 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
30130 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
30140 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
30150 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
30160 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
30170 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
30180 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
30190 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
301a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
301b0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
301c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
301d0 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
301e0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
301f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
30200 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
30210 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
30220 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
30230 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
30240 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
30250 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
30260 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
30270 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30280 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
30290 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
302a0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
302b0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
302c0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
302d0 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
302e0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
302f0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
30300 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
30310 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30320 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
30330 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
30340 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
30350 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30360 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
30370 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
30380 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
30390 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
303a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
303b0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
303c0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
303d0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
303e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
303f0 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
30400 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
30410 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
30420 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
30430 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
30440 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
30450 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
30460 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30470 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
30480 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
30490 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
304a0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
304b0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
304c0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
304d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
304e0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
304f0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
30500 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
30510 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
30520 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
30530 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
30540 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
30550 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
30560 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
30570 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
30580 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
30590 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
305a0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
305b0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
305c0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
305d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
305e0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
305f0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
30600 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
30610 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
30620 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
30630 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
30640 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
30650 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
30660 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
30670 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
30680 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
30690 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
306a0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
306b0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
306c0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
306d0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
306e0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
306f0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
30700 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
30710 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
30720 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
30730 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
30740 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
30750 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
30760 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
30770 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
30780 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
30790 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
307a0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
307b0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
307c0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
307d0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
307e0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
307f0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
30800 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
30810 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
30820 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
30830 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30840 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
30850 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
30860 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
30870 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
30880 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
30890 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
308a0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
308b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
308c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
308d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
308e0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
308f0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
30900 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
30910 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
30920 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
30930 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
30940 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
30950 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
30960 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
30970 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30980 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
30990 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
309a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
309b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
309c0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
309d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
309e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
309f0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
30a00 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
30a10 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
30a20 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
30a30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30a40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30a50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
30a60 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
30a70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
30a80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
30a90 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
30aa0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30ab0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
30ac0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
30ad0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
30ae0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
30af0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30b00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
30b10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30b20 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
30b30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
30b40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30b50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
30b60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30b70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
30b80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30b90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
30ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30bb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
30bd0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
30be0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
30bf0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
30c00 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
30c10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
30c20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30c30 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
30c40 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
30c50 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
30c60 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
30c70 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
30c80 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
30c90 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
30ca0 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
30cb0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
30cc0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
30cd0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
30ce0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30cf0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
30d00 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
30d10 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
30d20 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
30d30 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
30d40 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
30d50 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
30d60 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
30d70 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
30d80 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
30d90 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
30da0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
30db0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
30dc0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
30dd0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
30de0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
30df0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
30e00 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
30e10 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
30e20 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
30e30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
30e40 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
30e50 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
30e60 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
30e70 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
30e80 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
30e90 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
30ea0 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
30eb0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
30ec0 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
30ed0 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
30ee0 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
30ef0 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
30f00 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
30f10 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
30f20 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
30f30 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
30f40 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
30f50 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
30f60 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
30f70 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
30f80 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30f90 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
30fa0 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
30fb0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
30fc0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
30fd0 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
30fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
30ff0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31000 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
31010 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
31020 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
31030 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
31040 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
31050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
31060 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
31070 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
31080 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
31090 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
310a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
310b0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
310c0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
310d0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
310e0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
310f0 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
31100 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
31110 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
31120 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
31130 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31140 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
31150 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
31160 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
31170 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
31180 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
31190 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
311a0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
311b0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
311c0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
311d0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
311e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
311f0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
31200 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
31210 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
31220 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
31230 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
31240 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
31250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
31260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
31270 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
31280 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
31290 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
312a0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
312b0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
312c0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
312d0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
312e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
312f0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
31300 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
31310 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
31320 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
31330 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
31340 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
31350 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
31360 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
31370 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31380 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31390 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
313a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
313b0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
313c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
313d0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
313e0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
313f0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
31400 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
31410 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
31420 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
31430 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
31440 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
31450 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
31460 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
31470 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
31480 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31490 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
314a0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
314b0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
314c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
314d0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
314e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
314f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
31500 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
31510 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
31520 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31530 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31540 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
31550 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
31560 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
31570 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
31580 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31590 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
315a0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
315b0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
315c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
315d0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
315e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
315f0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
31600 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
31610 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31620 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
31630 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
31640 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
31650 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31660 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
31670 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31680 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
31690 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
316a0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
316b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
316c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
316d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
316e0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
316f0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
31700 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31710 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31720 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
31730 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
31740 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
31750 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
31760 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
31770 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
31780 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
31790 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
317a0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
317b0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
317c0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
317d0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
317e0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
317f0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
31800 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
31810 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
31820 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
31830 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
31840 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
31850 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
31860 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
31870 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
31880 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
31890 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
318a0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
318b0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
318c0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
318d0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
318e0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
318f0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
31900 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
31910 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
31920 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
31930 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
31940 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
31950 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
31960 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
31970 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
31980 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
31990 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
319a0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
319b0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
319c0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
319d0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
319e0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
319f0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
31a00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
31a10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
31a20 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
31a30 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31a40 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
31a50 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
31a60 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
31a70 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
31a80 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
31a90 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
31aa0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
31ab0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31ac0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
31ad0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
31ae0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
31af0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
31b00 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
31b10 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
31b20 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
31b30 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
31b40 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
31b50 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
31b60 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
31b70 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
31b80 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
31b90 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
31ba0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
31bb0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
31bc0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
31bd0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
31be0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
31bf0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
31c00 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
31c10 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
31c20 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
31c30 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
31c40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31c50 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
31c60 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
31c70 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31c80 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
31c90 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
31ca0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
31cb0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
31cc0 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
31cd0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
31ce0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
31cf0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
31d00 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
31d10 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
31d20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
31d30 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
31d40 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
31d50 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
31d60 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
31d70 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
31d80 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
31d90 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
31da0 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
31db0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
31dc0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
31dd0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
31de0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
31df0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
31e00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
31e10 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
31e20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
31e30 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
31e40 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
31e50 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
31e60 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
31e70 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
31e80 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
31e90 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
31ea0 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
31eb0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
31ec0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
31ed0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
31ee0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
31ef0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
31f00 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
31f10 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
31f20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
31f30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
31f40 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
31f50 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
31f60 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
31f70 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
31f80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
31f90 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
31fa0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
31fb0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
31fc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31fd0 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
31fe0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
31ff0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
32000 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32010 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
32020 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
32030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32040 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
32050 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
32060 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
32070 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
32080 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
32090 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
320a0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
320b0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
320c0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
320d0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
320e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
320f0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
32100 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
32110 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
32120 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
32130 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
32140 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
32150 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
32160 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
32170 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
32180 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
32190 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
321a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
321b0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
321c0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
321d0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
321e0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
321f0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
32200 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
32210 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
32220 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
32230 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
32240 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
32250 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
32260 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
32270 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
32280 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
32290 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
322a0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
322b0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
322c0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
322d0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
322e0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
322f0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
32300 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
32310 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
32320 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
32330 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
32340 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
32350 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
32360 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
32370 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
32380 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
32390 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
323a0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
323b0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
323c0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
323d0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
323e0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
323f0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
32400 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32410 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
32420 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32430 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
32440 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
32450 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
32460 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
32470 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
32480 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
32490 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
324a0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
324b0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
324c0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
324d0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
324e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
324f0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
32500 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
32510 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
32520 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
32530 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
32540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32550 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
32560 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32570 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
32580 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
32590 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
325a0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
325b0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
325c0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
325d0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
325e0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
325f0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
32600 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
32610 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
32620 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
32630 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32640 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
32650 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
32660 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
32670 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32680 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32690 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
326a0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
326b0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
326c0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
326d0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
326e0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
326f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
32700 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32710 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
32720 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
32730 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
32740 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32750 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32760 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
32770 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
32780 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
32790 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
327a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
327b0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
327c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
327d0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
327e0 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
327f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
32800 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
32810 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
32820 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
32830 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
32840 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
32850 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
32860 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32870 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
32880 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32890 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
328a0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
328b0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
328c0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
328d0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
328e0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
328f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32900 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
32910 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
32920 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
32930 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
32940 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
32950 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
32960 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
32970 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
32980 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
32990 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
329a0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
329b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
329c0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
329d0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
329e0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
329f0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
32a00 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
32a10 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
32a20 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
32a30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
32a40 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
32a50 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
32a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a70 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
32a80 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
32a90 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
32aa0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
32ab0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
32ac0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
32ad0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
32ae0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
32af0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32b00 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
32b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32b20 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
32b30 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
32b40 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
32b50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
32b60 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
32b70 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
32b80 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
32b90 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
32ba0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
32bb0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
32bc0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
32bd0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
32be0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32bf0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
32c00 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
32c10 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
32c20 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
32c30 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
32c40 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
32c50 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
32c60 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
32c70 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
32c80 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
32c90 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
32ca0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
32cb0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
32cc0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
32cd0 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
32ce0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
32cf0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
32d00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32d10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32d20 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
32d30 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
32d40 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
32d50 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
32d60 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
32d70 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
32d80 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
32d90 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
32da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32db0 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
32dc0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
32dd0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
32de0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
32df0 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
32e00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
32e10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
32e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32e30 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
32e40 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
32e50 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
32e60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32e70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32e80 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
32e90 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
32ea0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
32eb0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
32ec0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32ed0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
32ee0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
32ef0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
32f00 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
32f10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32f20 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
32f30 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
32f40 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
32f50 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
32f60 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
32f70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32f80 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
32f90 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
32fa0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
32fb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32fc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32fd0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
32fe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32ff0 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
33000 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33010 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
33020 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33030 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
33040 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
33050 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
33060 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
33070 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
33080 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33090 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
330a0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
330b0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
330c0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
330d0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
330e0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
330f0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
33100 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
33110 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
33120 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
33130 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
33140 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
33150 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
33160 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
33170 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
33180 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33190 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
331a0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
331b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
331c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
331d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
331e0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
331f0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
33200 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
33210 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
33220 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
33230 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
33240 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
33250 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
33260 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
33270 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
33280 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
33290 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
332a0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
332b0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
332c0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
332d0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
332e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
332f0 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
33300 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33310 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
33320 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
33330 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
33340 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
33350 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
33360 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
33370 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
33380 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
33390 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
333a0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
333b0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
333c0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
333d0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
333e0 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
333f0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
33400 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
33410 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
33420 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
33430 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
33440 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
33450 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
33460 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
33470 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
33480 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
33490 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
334a0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
334b0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
334c0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
334d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
334e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
334f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33500 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33510 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
33520 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
33530 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
33540 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
33550 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
33560 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
33570 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
33580 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
33590 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
335a0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
335b0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
335c0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
335d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
335e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
335f0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
33600 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
33610 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
33620 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
33630 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
33640 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
33650 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
33660 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
33670 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
33680 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
33690 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
336a0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
336b0 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
336c0 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
336d0 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
336e0 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
336f0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
33700 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
33710 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
33720 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
33730 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
33740 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
33750 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33760 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
33770 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
33780 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
33790 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
337a0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
337b0 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
337c0 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
337d0 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
337e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
337f0 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
33800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33810 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
33820 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33830 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
33840 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
33850 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33860 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
33870 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
33880 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33890 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
338a0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
338b0 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
338c0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
338d0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
338e0 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
338f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33900 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
33910 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
33920 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
33930 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
33940 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
33950 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
33960 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
33970 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
33980 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
33990 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
339a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
339b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
339c0 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
339d0 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
339e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
339f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
33a00 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
33a10 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
33a20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33a30 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
33a40 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
33a50 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
33a60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
33a70 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
33a80 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
33a90 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
33aa0 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
33ab0 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
33ac0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33ad0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
33ae0 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
33af0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
33b00 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
33b10 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
33b20 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
33b30 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33b40 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
33b50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33b60 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
33b70 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
33b80 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33b90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
33ba0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
33bb0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
33bc0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
33bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33be0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
33bf0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
33c00 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  r*, int);.SQLITE
33c10 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33c20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33c30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33c40 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
33c50 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
33c60 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33c70 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
33c80 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
33c90 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
33ca0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33cb0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
33cc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33cd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
33ce0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33cf0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
33d00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33d10 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
33d20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33d30 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
33d40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
33d50 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
33d60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33d70 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
33d80 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
33d90 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
33da0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
33db0 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
33dc0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
33dd0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
33de0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33df0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
33e00 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
33e10 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
33e20 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
33e30 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
33e40 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
33e50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33e60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
33e70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33e80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
33e90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33ea0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
33eb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33ec0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
33ed0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
33ee0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
33ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33f00 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
33f10 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
33f20 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
33f30 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
33f40 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33f50 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
33f60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33f70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
33f80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
33f90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33fa0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
33fb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33fc0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
33fd0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
33fe0 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
33ff0 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
34000 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
34010 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
34020 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
34030 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
34040 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
34050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
34060 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
34070 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
34080 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
34090 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
340a0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
340b0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
340c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
340d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
340e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
340f0 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
34100 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
34110 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
34120 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
34130 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
34140 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
34150 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
34160 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
34170 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
34180 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
34190 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
341a0 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
341b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
341c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
341d0 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
341e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
341f0 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
34200 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
34210 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
34220 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
34230 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
34240 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
34250 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
34260 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
34270 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
34280 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
34290 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
342a0 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
342b0 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
342c0 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
342d0 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
342e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
342f0 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
34300 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
34310 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
34320 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
34330 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
34340 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
34350 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
34360 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
34370 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
34380 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
34390 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
343a0 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
343b0 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
343c0 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
343d0 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
343e0 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
343f0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
34400 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
34410 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34420 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
34430 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
34440 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
34450 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
34460 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34470 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
34480 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
34490 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
344a0 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
344b0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
344c0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
344d0 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
344e0 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
344f0 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
34500 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
34510 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
34520 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
34530 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
34540 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
34550 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
34560 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
34570 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
34580 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
34590 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
345a0 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
345b0 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
345c0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
345d0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
345e0 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
345f0 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
34600 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
34610 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
34620 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
34630 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
34640 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
34650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
34660 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
34670 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
34680 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
34690 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
346a0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
346b0 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
346c0 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
346d0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
346e0 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
346f0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
34700 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
34710 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
34720 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
34730 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
34740 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
34750 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
34760 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
34770 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
34780 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
34790 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
347a0 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
347b0 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
347c0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
347d0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
347e0 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
347f0 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
34800 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
34810 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
34820 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
34830 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
34840 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
34850 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
34860 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
34870 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
34880 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
34890 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
348a0 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
348b0 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
348c0 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
348d0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
348e0 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
348f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
34900 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
34910 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
34920 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
34930 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
34940 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
34950 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
34960 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
34970 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
34980 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
34990 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
349a0 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
349b0 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
349c0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
349d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
349e0 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
349f0 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
34a00 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
34a10 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
34a20 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
34a30 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
34a40 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
34a50 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
34a60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34a70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
34a80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34a90 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
34aa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34ab0 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
34ac0 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
34ad0 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
34ae0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34af0 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
34b00 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
34b10 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
34b20 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
34b30 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
34b40 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
34b50 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
34b60 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
34b70 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
34b80 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
34b90 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
34ba0 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
34bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34bc0 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
34bd0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
34be0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
34bf0 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
34c00 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
34c10 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
34c20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34c30 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
34c40 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
34c50 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
34c60 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
34c70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34c80 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
34c90 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
34ca0 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
34cb0 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
34cc0 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
34cd0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
34ce0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34cf0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
34d00 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
34d10 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
34d20 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
34d30 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
34d40 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
34d50 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
34d60 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
34d70 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
34d80 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
34d90 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
34da0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
34db0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
34dc0 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
34dd0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
34de0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
34df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34e00 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
34e10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
34e20 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
34e30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34e40 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
34e50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
34e60 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
34e70 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
34e80 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
34e90 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
34ea0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
34eb0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
34ec0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
34ed0 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
34ee0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34ef0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34f00 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
34f10 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
34f20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
34f30 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
34f40 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
34f50 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
34f60 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
34f70 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
34f80 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
34f90 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  y)(void*).);.SQL
34fa0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34fb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34fc0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
34fd0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
34fe0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
34ff0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
35000 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
35010 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
35020 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
35030 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
35040 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
35050 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
35060 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
35070 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
35080 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
35090 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
350a0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
350b0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
350c0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
350d0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
350e0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
350f0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
35100 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
35110 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
35120 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
35130 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
35140 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
35150 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
35160 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
35170 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
35180 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
35190 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
351a0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
351b0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
351c0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
351d0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
351e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
351f0 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
35200 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
35210 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
35220 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35230 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
35240 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
35250 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
35260 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
35270 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
35280 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
35290 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
352a0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
352b0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
352c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
352d0 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
352e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
352f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35300 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
35310 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
35320 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
35330 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
35340 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
35350 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
35360 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
35370 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
35380 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
35390 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
353a0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
353b0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
353c0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
353d0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
353e0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
353f0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
35400 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
35410 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
35420 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
35430 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
35440 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
35450 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
35460 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
35470 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
35480 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
35490 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
354a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
354b0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
354c0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
354d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
354e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
354f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
35500 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
35510 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
35520 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
35530 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35540 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  on_v2()]..*/.SQL
35550 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35560 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35570 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
35580 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
35590 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
355a0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
355b0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
355c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
355d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
355e0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
355f0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
35600 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
35610 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
35620 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
35630 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
35640 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
35650 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
35660 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
35670 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
35680 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
35690 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
356a0 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
356b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
356c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
356d0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
356e0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
356f0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
35700 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
35710 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
35720 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
35730 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
35740 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
35750 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
35760 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
35770 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
35780 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
35790 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
357a0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
357b0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
357c0 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
357d0 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
357e0 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
357f0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
35800 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
35810 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
35820 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
35830 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
35840 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
35850 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
35860 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
35870 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
35880 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
35890 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
358a0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
358b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
358c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
358d0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
358e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
358f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
35900 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
35910 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
35920 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
35930 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
35940 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
35950 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
35960 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
35970 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
35980 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
35990 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
359a0 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
359b0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
359c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
359d0 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
359e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
359f0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
35a00 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
35a10 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
35a20 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
35a30 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
35a40 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
35a50 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
35a60 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
35a70 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
35a80 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
35a90 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
35aa0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
35ab0 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
35ac0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
35ad0 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
35ae0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
35af0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
35b00 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
35b10 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
35b20 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
35b30 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
35b40 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
35b50 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
35b60 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
35b70 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
35b80 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
35b90 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
35ba0 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
35bb0 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
35bc0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
35bd0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
35be0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
35bf0 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
35c00 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
35c10 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
35c20 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
35c30 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
35c40 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
35c50 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
35c60 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
35c70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
35c80 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
35c90 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
35ca0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
35cb0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
35cc0 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
35cd0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
35ce0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
35cf0 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
35d00 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
35d10 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
35d20 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
35d30 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
35d40 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
35d50 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
35d60 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
35d70 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
35d80 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
35d90 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
35da0 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
35db0 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
35dc0 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
35dd0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
35de0 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
35df0 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
35e00 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
35e10 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
35e20 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c  ragraphs..*/.SQL
35e30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35e40 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
35e50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35e60 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
35e70 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
35e80 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
35e90 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
35ea0 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
35eb0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
35ec0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
35ed0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
35ee0 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
35ef0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
35f00 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
35f10 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
35f20 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
35f30 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
35f40 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
35f50 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
35f60 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
35f70 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
35f80 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
35f90 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
35fa0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
35fb0 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
35fc0 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
35fd0 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
35fe0 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
35ff0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
36000 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
36010 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
36020 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
36030 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
36040 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
36050 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
36060 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
36070 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
36080 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
36090 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
360a0 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
360b0 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
360c0 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
360d0 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
360e0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
360f0 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
36100 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
36110 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
36120 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
36130 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
36140 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
36150 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
36160 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
36170 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
36180 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
36190 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
361a0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
361b0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
361c0 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
361d0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
361e0 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
361f0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
36200 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
36210 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
36220 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
36230 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
36240 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
36250 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
36260 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
36270 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
36280 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
36290 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
362a0 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
362b0 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
362c0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
362d0 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
362e0 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
362f0 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
36300 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
36310 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
36320 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
36330 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
36340 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
36350 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
36360 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
36370 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
36380 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36390 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
363a0 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
363b0 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
363c0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
363d0 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
363e0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
363f0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
36400 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
36410 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
36420 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
36430 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
36440 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
36450 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
36460 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
36470 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
36480 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
36490 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
364a0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
364b0 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
364c0 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
364d0 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
364e0 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
364f0 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
36500 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
36510 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
36520 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
36530 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
36540 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
36550 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
36560 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
36570 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
36580 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
36590 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
365a0 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
365b0 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
365c0 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
365d0 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
365e0 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
365f0 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
36600 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
36610 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
36620 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
36630 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
36640 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
36650 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
36660 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
36670 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
36680 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
36690 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
366a0 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te>.*/.SQLITE_AP
366b0 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
366c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
366d0 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
366e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
366f0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
36700 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
36710 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
36720 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
36730 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
36740 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
36750 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
36760 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
36770 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
36780 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
36790 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
367a0 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
367b0 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
367c0 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
367d0 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
367e0 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
367f0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
36800 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
36810 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
36820 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
36830 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
36840 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
36850 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
36860 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
36870 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
36880 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
36890 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
368a0 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
368b0 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
368c0 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
368d0 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
368e0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
368f0 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
36900 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
36910 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
36920 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
36930 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
36940 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
36950 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
36960 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
36970 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
36980 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
36990 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
369a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
369b0 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
369c0 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
369d0 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
369e0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
369f0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
36a00 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
36a10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
36a20 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
36a30 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
36a40 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36a50 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36a60 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
36a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36a80 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
36a90 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
36aa0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
36ab0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
36ac0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
36ad0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
36ae0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
36af0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
36b00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
36b10 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
36b20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
36b30 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
36b40 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
36b50 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36b60 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
36b70 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
36b80 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
36b90 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36ba0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
36bb0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
36bc0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
36bd0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
36be0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
36bf0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36c00 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
36c10 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
36c20 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36c30 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
36c40 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
36c50 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
36c60 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
36c70 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
36c80 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
36c90 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
36ca0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
36cb0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
36cc0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
36cd0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
36ce0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
36cf0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
36d00 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
36d10 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
36d20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
36d30 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
36d40 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
36d50 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
36d60 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
36d70 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
36d80 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
36d90 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
36da0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36db0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
36dc0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
36dd0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
36de0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
36df0 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64   *sqlite3_data_d
36e00 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
36e10 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
36e20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
36e30 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
36e40 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
36e50 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
36e60 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
36e70 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
36e80 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
36e90 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
36ea0 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
36eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
36ec0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
36ed0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
36ee0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
36ef0 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
36f00 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
36f10 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
36f20 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
36f30 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
36f40 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
36f50 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
36f60 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
36f70 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
36f80 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
36f90 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
36fa0 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
36fb0 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
36fc0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
36fd0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
36fe0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
36ff0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
37000 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
37010 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
37020 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
37030 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
37040 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
37050 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
37060 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
37070 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
37080 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
37090 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
370a0 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
370b0 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
370c0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
370d0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
370e0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
370f0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
37100 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
37110 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
37120 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
37130 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
37140 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
37150 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37160 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
37170 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
37180 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
37190 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73  turn value.** is
371a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
371b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
371c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
371d0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
371e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
371f0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
37200 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
37210 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
37220 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
37230 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
37240 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37250 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37260 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
37270 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
37280 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37290 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
372a0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
372b0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
372c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
372d0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
372e0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
372f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
37300 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
37310 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
37320 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
37330 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
37340 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
37350 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
37360 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
37370 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
37380 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
37390 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
373a0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
373b0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
373c0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
373d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
373e0 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46  n The Filename F
373f0 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  or A Database Co
37400 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
37410 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66  The sqlite3_db_f
37420 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74  ilename(D,N) int
37430 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37440 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69   pointer to a fi
37450 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69  lename.** associ
37460 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61  ated with databa
37470 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69  se N of connecti
37480 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e  on D.  ^The main
37490 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
374a0 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22  * has the name "
374b0 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65  main".  If there
374c0 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20   is no attached 
374d0 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68  database N on th
374e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
374f0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69  nnection D, or i
37500 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20  f database N is 
37510 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69  a temporary or i
37520 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
37530 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c  e, then.** a NUL
37540 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
37550 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
37560 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72  e filename retur
37570 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
37580 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70  tion is the outp
37590 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75  ut of the.** xFu
375a0 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f  llPathname metho
375b0 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20  d of the [VFS]. 
375c0 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   ^In other words
375d0 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  , the filename.*
375e0 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73  * will be an abs
375f0 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20  olute pathname, 
37600 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65  even if the file
37610 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20  name used.** to 
37620 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
37630 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73  e originally was
37640 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69   a URI or relati
37650 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a  ve pathname..*/.
37660 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
37670 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
37680 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74  b_filename(sqlit
37690 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
376a0 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
376b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
376c0 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61  etermine if a da
376d0 74 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f  tabase is read-o
376e0 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nly.**.** ^The s
376f0 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e  qlite3_db_readon
37700 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  ly(D,N) interfac
37710 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74  e returns 1 if t
37720 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a  he database N.**
37730 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   of connection D
37740 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30   is read-only, 0
37750 20 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77   if it is read/w
37760 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e  rite, or -1 if N
37770 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e   is not.** the n
37780 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ame of a databas
37790 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e on connection 
377a0 44 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  D..*/.SQLITE_API
377b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
377c0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
377d0 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
377e0 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a   *zDbName);../*.
377f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
37800 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
37810 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
37820 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
37830 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
37840 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
37850 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
37860 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
37870 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
37880 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
37890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
378a0 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20  pDb.  ^If pStmt 
378b0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
378c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
378d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
378e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
378f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37900 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
37910 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
37920 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
37930 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65    ^If no prepare
37940 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
37950 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
37960 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
37970 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
37980 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
37990 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
379a0 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
379b0 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
379c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
379d0 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
379e0 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
379f0 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
37a00 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
37a10 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
37a20 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
37a30 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  ointer..*/.SQLIT
37a40 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 73 74  E_API sqlite3_st
37a50 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74  mt *sqlite3_next
37a60 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70  _stmt(sqlite3 *p
37a70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  Db, sqlite3_stmt
37a80 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
37a90 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
37aa0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
37ab0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
37ac0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
37ad0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
37ae0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
37af0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
37b00 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
37b10 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
37b20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
37b30 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
37b40 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
37b50 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
37b60 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
37b70 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
37b80 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
37b90 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
37ba0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37bb0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
37bc0 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  en..** ^The sqli
37bd0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37be0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
37bf0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
37c00 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
37c10 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
37c20 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
37c30 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b  ion is [ROLLBACK
37c40 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e   | rolled back].
37c50 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
37c60 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
37c70 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
37c80 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37c90 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
37ca0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
37cb0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
37cc0 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70  idden..** ^The p
37cd0 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
37ce0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
37cf0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
37d00 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
37d10 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
37d20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  hook function re
37d30 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a  turns non-zero,.
37d40 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ** then the comm
37d50 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
37d60 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
37d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37d80 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
37d90 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74  D,C,P) and sqlit
37da0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37db0 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
37dc0 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20  s.** return the 
37dd0 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
37de0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
37df0 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  l of the same fu
37e00 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65  nction.** on the
37e10 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
37e20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
37e30 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
37e40 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
37e50 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f   each function o
37e60 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n D..**.** The c
37e70 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61  ommit and rollba
37e80 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  ck hook callback
37e90 73 20 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72  s are not reentr
37ea0 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ant..** The call
37eb0 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  back implementat
37ec0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
37ed0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
37ee0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
37ef0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37f00 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
37f10 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  d the callback. 
37f20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
37f30 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
37f40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37f50 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
37f60 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
37f70 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
37f80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
37f90 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
37fa0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
37fb0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f   commit.** or ro
37fc0 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74  llback hook in t
37fd0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
37fe0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e  ** Note that run
37ff0 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  ning any other S
38000 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69  QL statements, i
38010 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20  ncluding SELECT 
38020 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f  statements,.** o
38030 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67  r merely calling
38040 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
38050 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
38060 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
38070 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
38080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38090 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
380a0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
380b0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
380c0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73  ph..**.** ^Regis
380d0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
380e0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
380f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
38100 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f  .** ^When the co
38110 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
38120 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
38130 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
38140 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
38150 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
38160 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
38170 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d  ly.  ^If the com
38180 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75  mit hook.** retu
38190 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
381a0 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20  en the [COMMIT] 
381b0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
381c0 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a  o a [ROLLBACK]..
381d0 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
381e0 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64   hook is invoked
381f0 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74   on a rollback t
38200 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  hat results from
38210 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f   a commit.** hoo
38220 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d  k returning non-
38230 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74  zero, just as it
38240 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61   would be with a
38250 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63  ny other rollbac
38260 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  k..**.** ^For th
38270 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
38280 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
38290 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
382a0 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f   have been.** ro
382b0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
382c0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
382d0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
382e0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
382f0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
38300 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
38310 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
38320 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
38330 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63   ^The rollback c
38340 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
38350 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
38360 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
38370 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
38380 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
38390 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
383a0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
383b0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
383c0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  o the [sqlite3_u
383d0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e  pdate_hook()] in
383e0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49  terface..*/.SQLI
383f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
38400 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
38410 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
38420 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
38430 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
38440 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
38450 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
38460 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
38470 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
38480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
38490 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
384a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
384b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
384c0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
384d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
384e0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
384f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  function.** with
38500 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
38510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74  onnection] ident
38520 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
38530 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
38540 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
38550 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
38560 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
38570 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
38580 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
38590 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
385a0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
385b0 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65  ction.** for the
385c0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
385d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
385e0 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rridden..**.** ^
385f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
38600 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
38610 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
38620 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
38630 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61  a.** row is upda
38640 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
38650 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68   deleted..** ^Th
38660 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38670 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
38680 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
38690 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
386a0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
386b0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
386c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c   ^The second cal
386d0 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
386e0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
386f0 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
38700 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72  E_DELETE],.** or
38710 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
38720 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
38730 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
38740 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
38750 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69  lback.** to be i
38760 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
38770 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
38780 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
38790 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
387a0 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
387b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61  he.** databas