System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 1faa238401198720acae465f72ec93106050d86c:


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 30 2d 31 35 20 32 30 3a 32 38 3a 32 32 20  -10-15 20:28:22 
1080: 32 63 33 61 66 36 35 37 66 65 65 36 31 35 33 38  2c3af657fee61538
1090: 34 32 64 36 36 30 61 36 63 65 32 39 61 61 37 64  42d660a6ce29aa7d
10a0: 37 39 31 65 62 64 33 38 22 0a 0a 2f 2a 0a 2a 2a  791ebd38"../*.**
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 4c 4f 43 4b 45  ine SQLITE_LOCKE
55b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
55d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
55f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5600: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5610: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5630: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5650: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5670: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5680: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5690: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56b0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
56c0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
56d0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
56e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56f0: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5700: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5710: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5720: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5730: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5740: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5750: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5770: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5780: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5790: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
57a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
57c0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
57d0: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
57e0: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
57f0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5800: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5810: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5820: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5830: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5840: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5850: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5860: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5870: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5880: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5890: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
58a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
58b0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
58c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
58e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
58f0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5900: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5910: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5920: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5930: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5940: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5950: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5960: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5970: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5980: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5990: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
59a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
59b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59c0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
59d0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
59e0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
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 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5a10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a20: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* 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 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5a50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a60: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* 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 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5a90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5aa0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5ab0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ac0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ad0: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5ae0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5af0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5b00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b20: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5b30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5b40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
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 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
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 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5bb0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
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 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5bf0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
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 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5c30: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
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 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5c70: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
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 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5cb0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
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 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5cf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5d00: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d30: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5d40: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5d50: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5d90: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5da0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5db0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5dc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dd0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5de0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5df0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5e00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e20: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5e30: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5e40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5e50: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5e70: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5e80: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5e90: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5ea0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5eb0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5ec0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5ed0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5ee0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5ef0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5f00: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5f10: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5f20: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5f30: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5f40: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5f50: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5f60: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5f70: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5f80: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5f90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5fa0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5fb0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5fc0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5fd0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5fe0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5ff0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6000: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6010: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6020: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6030: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6040: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6050: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6060: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6070: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6080: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6090: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
60a0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
60b0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
60c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
60d0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
60e0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
60f0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6100: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6110: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6120: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6130: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6140: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6150: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6160: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6170: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6180: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6190: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
61a0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
61b0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
61c0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
61d0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
61e0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
61f0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6200: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6210: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6220: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6230: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6240: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6250: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6260: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6270: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6280: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6290: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
62a0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
62b0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
62c0: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
62d0: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
62e0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
62f0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6300: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6310: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
6320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6330: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6340: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6350: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6360: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6370: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6380: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6390: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
63a0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
63b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
63c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63f0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6400: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6410: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6420: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6440: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6450: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6460: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6470: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6480: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6490: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
64a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
64b0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
64c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
64d0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
64e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
64f0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6500: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6510: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6520: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6530: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6540: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6550: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6560: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6570: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6580: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6590: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
65a0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
65b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
65c0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
65d0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
65e0: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
65f0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6600: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6610: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6620: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6630: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6640: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6650: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6660: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6670: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6680: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6690: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
66a0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
66b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
66c0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
66d0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
66e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
66f0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6700: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6710: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6730: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6740: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6750: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6760: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6770: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6780: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6790: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
67a0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
67b0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
67c0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
67d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
67e0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
67f0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6800: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6810: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6820: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6830: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6840: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6850: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6860: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6870: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6880: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6890: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
68a0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
68b0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
68c0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
68d0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
68e0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
68f0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6900: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6910: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6920: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6930: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6940: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6950: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6960: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6970: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6980: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6990: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
69a0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
69b0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
69c0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
69d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
69e0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
69f0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6a00: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6a10: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6a20: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6a30: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6a40: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6a50: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
6a60: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
6a70: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6a80: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6a90: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6aa0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6ab0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6ac0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6ad0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6ae0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6af0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6b00: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6b10: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6b20: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6b30: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6b40: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6b50: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6b60: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6b70: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6b80: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6b90: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6ba0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6bb0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6bc0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6bd0: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6be0: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6bf0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6c00: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6c10: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6c20: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6c30: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6c40: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6c50: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6c60: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6c70: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6c90: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6ca0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6cb0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6cc0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6cd0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6ce0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6cf0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6d00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6d10: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6d20: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6d30: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6d40: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6d50: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6d60: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6d70: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6d80: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6d90: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6da0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6db0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6dc0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6dd0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6de0: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6df0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6e00: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6e10: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6e20: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6e30: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6e40: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6e50: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6e60: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6e70: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6e80: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6e90: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6ea0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6eb0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6ec0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6ed0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6ee0: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6ef0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6f00: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6f10: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6f20: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6f30: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6f40: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6f50: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6f60: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6f70: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6f80: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6f90: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6fa0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6fb0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6fc0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6fd0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6fe0: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6ff0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7000: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7010: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7020: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7030: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
7040: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7050: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7060: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7070: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7080: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7090: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
70a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
70b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
70c0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
70d0: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
70e0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
70f0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7100: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7110: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7120: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7130: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7140: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7150: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7160: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7170: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7180: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7190: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
71a0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
71b0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
71c0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
71d0: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
71e0: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
71f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7200: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7210: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7220: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7230: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7240: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7250: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7260: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7270: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7280: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7290: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
72a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
72b0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
72c0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
72d0: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
72e0: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
72f0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7300: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7310: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7320: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7330: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7340: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7350: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7360: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7370: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7380: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7390: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
73a0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
73b0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
73c0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
73d0: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
73e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
73f0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7400: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7410: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7420: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7430: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7440: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7450: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7460: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7470: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7480: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7490: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
74a0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
74b0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
74c0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
74d0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
74e0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
74f0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7500: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7510: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7520: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7530: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7540: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7550: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7560: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7570: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7580: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7590: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
75a0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
75b0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
75c0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
75d0: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
75e0: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
75f0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7600: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7610: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7620: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7630: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7640: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7650: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7660: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7670: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7680: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7690: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
76a0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
76b0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
76c0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
76d0: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
76e0: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
76f0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7700: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7710: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7720: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7730: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7740: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7750: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7760: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7770: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7780: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7790: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
77a0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
77b0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
77c0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
77d0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
77e0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
77f0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7800: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7810: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7820: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7830: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7840: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7850: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7860: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7870: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7880: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7890: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
78a0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
78b0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
78c0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
78d0: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
78e0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
78f0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7900: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7910: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7920: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7930: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7940: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7950: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
7960: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
7970: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7980: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7990: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
79a0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
79b0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
79c0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
79d0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
79e0: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
79f0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7a00: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7a10: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7a20: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7a30: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7a40: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7a50: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
7a60: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7a70: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7a80: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7a90: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7aa0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7ab0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7ac0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7ad0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7ae0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b00: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7b10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7b20: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b40: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7b50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b60: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7b70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b80: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7b90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ba0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7bb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7bc0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7be0: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7bf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7c00: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7c20: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7c30: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7c40: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7c50: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7c60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7c70: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7c80: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7c90: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7ca0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7cb0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7cc0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7cd0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7ce0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7cf0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7d00: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7d10: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7d20: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7d30: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7d40: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7d50: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7d60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7d70: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7d80: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7d90: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7da0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7db0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7dc0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7dd0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7de0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7df0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7e00: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7e10: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7e20: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7e30: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7e40: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7e50: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7e60: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7e70: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7e80: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7e90: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7ea0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7eb0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7ec0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7ed0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7ee0: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7ef0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7f00: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7f10: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7f20: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7f30: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7f40: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7f50: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7f60: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7f70: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7f80: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7f90: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7fa0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7fb0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7fc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7fd0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7fe0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7ff0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8000: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8010: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8020: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8030: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
8040: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8050: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8060: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8070: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8080: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8090: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
80a0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
80b0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
80c0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
80d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
80e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
80f0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8100: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8110: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8120: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8130: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8140: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8150: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
8160: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
8170: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8180: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8190: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
81a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
81b0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
81c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
81d0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
81e0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
81f0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8200: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8210: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
8220: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
8230: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8240: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8250: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
8260: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
8270: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8280: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8290: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
82a0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
82b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
82c0: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
82d0: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
82e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
82f0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8300: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8310: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
8320: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
8330: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
8340: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8350: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
8360: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8370: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8380: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8390: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
83a0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
83b0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
83c0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
83d0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
83e0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
83f0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8400: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8410: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
8420: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8430: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8440: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8450: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8460: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8470: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8480: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8490: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
84a0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
84b0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
84c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
84d0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
84e0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
84f0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8500: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8510: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8520: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8530: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8540: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8550: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8560: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8570: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8580: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8590: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
85a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
85b0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
85c0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
85d0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
85e0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
85f0: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8600: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8610: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8620: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8630: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
8640: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
8650: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
8660: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
8670: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
8680: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8690: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
86a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
86b0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
86c0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
86d0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
86e0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
86f0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8700: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8710: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8720: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8730: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8740: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8750: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
8760: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
8770: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8780: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8790: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
87a0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
87b0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
87c0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
87d0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
87e0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
87f0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8800: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8810: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8820: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8830: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8840: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8860: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
8870: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8880: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8890: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
88a0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
88b0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
88c0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
88d0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
88e0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
88f0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8900: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8910: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
8920: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8930: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8940: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8950: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
8960: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
8970: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8980: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8990: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
89a0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
89b0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
89c0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
89d0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
89e0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
89f0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8a00: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8a10: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
8a20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8a30: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8a40: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
8a50: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
8a60: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
8a70: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8a80: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8a90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8aa0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8ab0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8ac0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8ad0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8ae0: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8af0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8b00: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8b10: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8b20: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8b30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8b40: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8b50: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8b70: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8b80: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8b90: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8ba0: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8bb0: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8bc0: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8bd0: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8be0: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8bf0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8c00: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8c10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8c20: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8c30: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8c40: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8c50: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8c60: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8c70: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8c80: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8c90: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8ca0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8cb0: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8cc0: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8cd0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8ce0: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8cf0: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8d00: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8d10: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8d20: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8d30: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8d40: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8d50: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8d60: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8d70: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8d80: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8d90: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8da0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8db0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8dc0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8dd0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8de0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8df0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8e00: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8e10: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8e20: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8e30: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8e40: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8e50: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8e60: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8e70: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8e80: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8e90: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8ea0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8eb0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8ec0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8ed0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8ee0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8ef0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8f00: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8f10: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8f20: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8f30: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8f40: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8f50: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8f60: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8f70: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8f80: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8f90: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8fa0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8fb0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
8fc0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
8fd0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
8fe0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
8ff0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9000: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9010: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9020: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9030: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9040: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9050: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9060: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
9070: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9080: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9090: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
90a0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
90b0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
90c0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
90d0: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
90e0: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
90f0: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9100: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9110: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9120: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9130: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9140: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9150: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
9160: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
9170: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9180: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9190: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
91a0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
91b0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
91c0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
91d0: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
91e0: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
91f0: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9200: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9210: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9220: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9230: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9240: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9250: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9260: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9270: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9280: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9290: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
92a0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
92b0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
92c0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
92d0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
92e0: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
92f0: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9300: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9310: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9320: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9330: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9340: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9350: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
9360: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
9370: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9380: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9390: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
93a0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
93b0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
93c0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
93d0: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
93e0: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
93f0: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9400: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9410: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9420: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
9430: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
9440: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
9450: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9460: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
9470: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
9480: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
9490: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
94a0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
94b0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
94c0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
94d0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
94e0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
94f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9500: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9510: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9520: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
9530: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
9540: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
9550: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
9560: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
9570: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9580: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9590: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
95a0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
95b0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
95c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
95d0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
95e0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
95f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9600: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9610: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9620: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9630: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9640: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
9650: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
9660: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
9670: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
9680: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
9690: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
96a0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
96b0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
96c0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
96d0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
96e0: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
96f0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9700: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9710: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9720: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9730: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9740: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9750: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
9760: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
9770: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
9780: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
9790: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
97a0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
97b0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
97c0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
97d0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
97e0: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
97f0: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9800: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9810: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9820: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
9830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9840: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9850: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
9860: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
9870: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
9880: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
9890: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
98a0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
98b0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
98c0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
98d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
98e0: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
98f0: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9900: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9910: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
9920: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
9930: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
9940: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
9950: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
9970: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
9980: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
9990: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
99a0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
99b0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
99c0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
99d0: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
99e0: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
99f0: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9a00: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9a10: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
9a20: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
9a30: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
9a40: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
9a50: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
9a60: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
9a70: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9a80: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9a90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9aa0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9ab0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9ac0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9ad0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9ae0: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9af0: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9b00: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9b10: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9b20: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9b30: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9b40: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9b50: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9b60: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9b70: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9b80: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9b90: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9ba0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9bb0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9bc0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9bd0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9be0: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9bf0: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9c00: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9c10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9c20: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9c30: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9c40: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9c50: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9c60: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9c70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9c80: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9c90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9ca0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9cb0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9cc0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9cd0: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9ce0: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9cf0: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9d00: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9d10: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9d20: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9d30: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9d40: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9d50: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9d60: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9d70: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9d80: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9d90: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9da0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9db0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9dc0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9dd0: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9de0: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9df0: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9e00: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9e10: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9e20: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9e30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9e40: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9e50: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9e60: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9e70: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9e80: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9e90: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9ea0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9eb0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9ec0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9ed0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9ee0: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9ef0: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9f00: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9f10: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9f20: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9f30: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9f40: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9f50: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9f60: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9f70: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9f80: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9f90: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9fa0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9fb0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
9fc0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9fd0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9fe0: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
9ff0: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
a000: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
a010: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
a020: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
a030: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
a040: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
a050: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
a060: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a070: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a080: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a090: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
a0a0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
a0b0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a0c0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a0d0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a0e0: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a0f0: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a100: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a110: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a120: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a130: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a140: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a150: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a160: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a170: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a180: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a190: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a1a0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a1b0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a1c0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a1d0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a1e0: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a1f0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f  tatements..** </
a200: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ul>.**.** <li>[[
a210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a220: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
a230: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a240: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a250: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a260: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a270: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a280: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a290: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a2a0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a2b0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a2c0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a2d0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a2e0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a2f0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a300: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a310: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a320: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a330: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a340: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a350: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a360: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a370: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a380: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a390: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a3a0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a3b0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a3c0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a3d0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a3e0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a3f0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a400: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a410: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a420: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a430: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a440: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a450: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a460: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a470: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a480: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a490: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a4a0: 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
a4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
a4c0: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
a4d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
a4e0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
a4f0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a500: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
a510: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
a520: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
a530: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
a540: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
a550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a560: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
a570: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
a580: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
a590: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
a5a0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
a5b0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
a5c0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
a5d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
a5e0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
a5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a600: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
a610: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
a620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a630: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a640: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
a650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a660: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
a670: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
a680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a690: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
a6a0: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
a6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a6c0: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
a6d0: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
a6e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a6f0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a700: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
a710: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a720: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
a730: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
a740: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
a750: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
a760: 20 20 20 20 20 20 31 35 0a 0a 2f 2a 0a 2a 2a 20        15../*.** 
a770: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
a780: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
a790: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
a7a0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
a7b0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
a7c0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
a7d0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
a7e0: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
a7f0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
a800: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
a810: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
a820: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
a830: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
a840: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
a850: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
a860: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
a870: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
a880: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
a890: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
a8a0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
a8b0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
a8c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a8d0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
a8e0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
a8f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a900: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
a910: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
a920: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
a930: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
a940: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a950: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
a960: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
a970: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
a980: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
a990: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
a9a0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
a9b0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
a9c0: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
a9d0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
a9e0: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
a9f0: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
aa00: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
aa10: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
aa20: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
aa30: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
aa40: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
aa50: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
aa60: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
aa70: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
aa80: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
aa90: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
aaa0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
aab0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
aac0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
aad0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
aae0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
aaf0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
ab00: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ab10: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
ab20: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
ab30: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
ab40: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
ab50: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
ab60: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
ab70: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
ab80: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
ab90: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
aba0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
abb0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
abc0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
abd0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
abe0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
abf0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
ac00: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
ac10: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
ac20: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
ac30: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
ac40: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
ac50: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
ac60: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
ac70: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
ac80: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
ac90: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
aca0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
acb0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
acc0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
acd0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
ace0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
acf0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
ad00: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
ad10: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
ad20: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
ad30: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
ad40: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
ad50: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
ad60: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
ad70: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
ad80: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
ad90: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ada0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
adb0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
adc0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
add0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
ade0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
adf0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
ae00: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
ae10: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
ae20: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
ae30: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
ae40: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
ae50: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
ae60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
ae70: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
ae80: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
ae90: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
aea0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
aeb0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
aec0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
aed0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
aee0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
aef0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
af00: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
af10: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
af20: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
af30: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
af40: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
af50: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
af60: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
af70: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
af80: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
af90: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
afa0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
afb0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
afc0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
afd0: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
afe0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
aff0: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
b000: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
b010: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
b020: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
b030: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
b040: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
b050: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
b060: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
b070: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
b080: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
b090: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
b0a0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
b0b0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
b0c0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
b0d0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
b0e0: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
b0f0: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
b100: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
b110: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
b120: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
b130: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
b140: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
b150: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
b160: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
b170: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
b180: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
b190: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
b1a0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
b1b0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b1c0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
b1d0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
b1e0: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
b1f0: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
b200: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
b210: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
b220: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
b230: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
b240: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
b250: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
b260: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
b270: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
b280: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
b290: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
b2a0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
b2b0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
b2c0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
b2d0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
b2e0: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
b2f0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
b300: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
b310: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
b320: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
b330: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
b340: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
b350: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
b360: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
b370: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
b380: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
b390: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
b3a0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
b3b0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
b3c0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
b3d0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
b3e0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
b3f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
b400: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
b410: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
b420: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
b430: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
b440: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
b450: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
b460: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
b470: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
b480: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
b490: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
b4a0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
b4b0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b4c0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
b4d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b4e0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
b4f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b500: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
b510: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b520: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
b530: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
b540: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
b550: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
b560: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
b570: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
b580: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
b590: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
b5a0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b5b0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
b5c0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
b5d0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
b5e0: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
b5f0: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
b600: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
b610: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
b620: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
b630: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
b640: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
b650: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
b660: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
b670: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
b680: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
b690: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
b6a0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
b6b0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
b6c0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
b6d0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
b6e0: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
b6f0: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
b700: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
b710: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
b720: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
b730: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
b740: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
b750: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
b760: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
b770: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
b780: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
b790: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
b7a0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
b7b0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
b7c0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
b7d0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
b7e0: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
b7f0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
b800: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
b810: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
b820: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
b830: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
b840: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b850: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
b860: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b870: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
b880: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
b890: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b8a0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
b8b0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
b8c0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
b8d0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
b8e0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b8f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
b900: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
b910: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
b920: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
b930: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
b940: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
b950: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
b960: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b970: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
b980: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
b990: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
b9a0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
b9b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
b9c0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
b9d0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
b9e0: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
b9f0: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
ba00: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
ba10: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
ba20: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
ba30: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
ba40: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
ba50: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
ba60: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
ba70: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
ba80: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
ba90: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
baa0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
bab0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
bac0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
bad0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
bae0: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
baf0: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
bb00: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
bb10: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
bb20: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
bb30: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
bb40: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
bb50: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
bb60: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
bb70: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
bb80: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
bb90: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
bba0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
bbb0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
bbc0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
bbd0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
bbe0: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
bbf0: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
bc00: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
bc10: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
bc20: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
bc30: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
bc40: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
bc50: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
bc60: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
bc70: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
bc80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
bc90: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
bca0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
bcb0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
bcc0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
bcd0: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
bce0: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
bcf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
bd00: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
bd10: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
bd20: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
bd30: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
bd40: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
bd50: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
bd60: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
bd70: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
bd80: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
bd90: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
bda0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
bdb0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
bdc0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
bdd0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
bde0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
bdf0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
be00: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
be10: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
be20: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
be30: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
be40: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
be50: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
be60: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
be70: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
be80: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
be90: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
bea0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
beb0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
bec0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
bed0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
bee0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
bef0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
bf00: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
bf10: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
bf20: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
bf30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
bf40: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
bf50: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
bf60: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
bf70: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
bf80: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
bf90: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
bfa0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
bfb0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
bfc0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
bfd0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
bfe0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
bff0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
c000: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
c010: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
c020: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
c030: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
c040: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
c050: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
c060: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
c070: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
c080: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
c090: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
c0a0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
c0b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
c0c0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
c0d0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
c0e0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
c0f0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
c100: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
c110: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
c120: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
c130: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
c140: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
c150: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
c160: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
c170: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
c180: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
c190: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
c1a0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
c1b0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
c1c0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
c1d0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
c1e0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
c1f0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
c200: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
c210: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
c220: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
c230: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
c240: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
c250: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
c260: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
c270: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
c280: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
c290: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
c2a0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
c2b0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
c2c0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
c2d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c2e0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
c2f0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
c300: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
c310: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
c320: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
c330: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
c340: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
c350: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
c360: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
c370: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
c380: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c390: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
c3a0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
c3b0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
c3c0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
c3d0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
c3e0: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
c3f0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
c400: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
c410: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
c420: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
c430: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
c440: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
c450: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
c460: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
c470: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
c480: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
c490: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
c4a0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
c4b0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
c4c0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
c4d0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
c4e0: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
c4f0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
c500: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
c510: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
c520: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
c530: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
c540: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
c550: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
c560: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
c570: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
c580: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
c590: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
c5a0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
c5b0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
c5c0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
c5d0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
c5e0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
c5f0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
c600: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
c610: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
c620: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
c630: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
c640: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
c650: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
c660: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
c670: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
c680: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
c690: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
c6a0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
c6b0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
c6c0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
c6d0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
c6e0: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
c6f0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
c700: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
c710: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
c720: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
c730: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
c740: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
c750: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
c760: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
c770: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
c780: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
c790: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
c7a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
c7b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
c7c0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
c7d0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
c7e0: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
c7f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
c800: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
c810: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
c820: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
c830: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
c840: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
c850: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
c860: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
c870: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
c880: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
c890: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
c8a0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
c8b0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
c8c0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
c8d0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
c8e0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
c8f0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
c900: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
c910: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
c920: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
c930: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
c940: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
c950: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
c960: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
c970: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
c980: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
c990: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c9a0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c9b0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
c9c0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
c9d0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c9e0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
c9f0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
ca00: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ca10: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ca20: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
ca30: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
ca40: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ca50: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ca60: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
ca70: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
ca80: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
ca90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
caa0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
cab0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
cac0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
cad0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
cae0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
caf0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
cb00: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
cb10: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
cb20: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
cb30: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
cb40: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
cb50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
cb60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
cb70: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
cb80: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
cb90: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
cba0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
cbb0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
cbc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
cbd0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
cbe0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
cbf0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
cc00: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
cc10: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
cc20: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
cc30: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
cc40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
cc50: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
cc60: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
cc70: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
cc80: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
cc90: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
cca0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
ccb0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
ccc0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
ccd0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
cce0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
ccf0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
cd00: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
cd10: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
cd20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
cd30: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
cd40: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
cd50: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
cd60: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
cd70: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
cd80: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
cd90: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
cda0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
cdb0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
cdc0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
cdd0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cde0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cdf0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ce00: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
ce10: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
ce20: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
ce30: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ce40: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ce50: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
ce60: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
ce70: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ce80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ce90: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
cea0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ceb0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
cec0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
ced0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
cee0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
cef0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
cf00: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
cf10: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
cf20: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
cf30: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
cf40: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
cf50: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
cf60: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
cf70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
cf80: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
cf90: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
cfa0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
cfb0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
cfc0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
cfd0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
cfe0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
cff0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
d000: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
d010: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
d020: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
d030: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
d040: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
d050: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
d060: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
d070: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
d080: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
d090: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
d0a0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d0b0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
d0c0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d0d0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
d0e0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d0f0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d100: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
d110: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
d120: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d130: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
d140: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
d150: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
d160: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
d170: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
d180: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
d190: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
d1a0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
d1b0: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
d1c0: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
d1d0: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
d1e0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
d1f0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
d200: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
d210: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
d220: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
d230: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
d240: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
d250: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d260: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d270: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
d280: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
d290: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d2a0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
d2b0: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
d2c0: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
d2d0: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
d2e0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
d2f0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
d300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d310: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
d320: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
d330: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d340: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
d350: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
d360: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
d370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d380: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
d390: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
d3a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d3b0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d3c0: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
d3d0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
d3e0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d3f0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
d400: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
d410: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
d420: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
d430: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
d440: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d450: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
d460: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
d470: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
d480: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
d490: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
d4a0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d4b0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
d4c0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
d4d0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
d4e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d4f0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
d500: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
d510: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d520: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
d530: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
d540: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
d550: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
d560: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
d570: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
d580: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
d590: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
d5a0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
d5b0: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
d5c0: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
d5d0: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
d5e0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
d5f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
d600: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
d610: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
d620: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
d630: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
d640: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d650: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
d660: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
d670: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
d680: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
d690: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
d6a0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d6b0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
d6c0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
d6d0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
d6e0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
d6f0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
d700: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
d710: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
d720: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
d730: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
d740: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
d750: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d760: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
d770: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
d780: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
d790: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
d7a0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
d7b0: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
d7c0: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
d7d0: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
d7e0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
d7f0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
d800: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
d810: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
d820: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d830: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
d840: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
d850: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
d860: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
d870: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
d880: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d890: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
d8a0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
d8b0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
d8c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
d8d0: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
d8e0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
d8f0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
d900: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
d910: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
d920: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
d930: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
d940: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
d950: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
d960: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
d970: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
d980: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
d990: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
d9a0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
d9b0: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
d9c0: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
d9d0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
d9e0: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
d9f0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
da00: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
da10: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
da20: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
da30: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
da40: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
da50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
da60: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
da70: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
da80: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
da90: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
daa0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
dab0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dac0: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
dad0: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
dae0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
daf0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
db00: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
db10: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
db20: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
db30: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
db40: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
db50: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
db60: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
db70: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
db80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
db90: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
dba0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
dbb0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
dbc0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
dbd0: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
dbe0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
dbf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
dc00: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
dc10: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
dc20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dc30: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
dc40: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
dc50: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
dc60: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
dc70: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
dc80: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
dc90: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
dca0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dcb0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
dcc0: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
dcd0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dce0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
dcf0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
dd00: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
dd10: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
dd20: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
dd30: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
dd40: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
dd50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
dd60: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
dd70: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
dd80: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
dd90: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
dda0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
ddb0: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
ddc0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
ddd0: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
dde0: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
ddf0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
de00: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
de10: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
de20: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
de30: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
de40: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
de50: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
de60: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
de70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
de80: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
de90: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
dea0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
deb0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
dec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ded0: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
dee0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
def0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
df00: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
df10: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
df20: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
df30: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
df40: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
df50: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
df60: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
df70: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
df80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
df90: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
dfa0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
dfb0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
dfc0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
dfd0: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
dfe0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
dff0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
e000: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
e010: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e020: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
e030: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
e040: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e050: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
e060: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
e070: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
e080: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
e090: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
e0a0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
e0b0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
e0c0: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
e0d0: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
e0e0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
e0f0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
e100: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e110: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
e120: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
e130: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
e140: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
e150: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
e160: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
e170: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
e180: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
e190: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
e1a0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
e1b0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e1c0: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
e1d0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e1e0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e1f0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
e200: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
e210: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
e220: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
e230: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
e240: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e250: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
e260: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
e270: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
e280: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
e290: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
e2a0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
e2b0: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
e2c0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
e2d0: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
e2e0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
e2f0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e300: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
e310: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
e320: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
e330: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
e340: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
e350: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e360: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
e370: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
e380: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
e390: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
e3a0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
e3b0: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
e3c0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
e3d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
e3e0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
e3f0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
e400: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
e410: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
e420: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
e430: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
e440: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
e450: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
e460: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
e470: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
e480: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
e490: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
e4a0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
e4b0: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
e4c0: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
e4d0: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
e4e0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
e4f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
e500: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
e510: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
e520: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e530: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
e540: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
e550: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
e560: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
e570: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
e580: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
e590: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
e5a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e5b0: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
e5c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
e5d0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
e5e0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
e5f0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
e600: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
e610: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e620: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
e630: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
e640: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
e650: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
e660: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
e670: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
e680: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e690: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
e6a0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
e6b0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
e6c0: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
e6d0: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
e6e0: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
e6f0: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
e700: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
e710: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
e720: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
e730: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
e740: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
e750: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
e760: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
e770: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
e780: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
e790: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
e7a0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
e7b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
e7c0: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
e7d0: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
e7e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
e7f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e800: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
e810: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
e820: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
e830: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
e840: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
e850: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
e860: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
e870: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
e880: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
e890: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
e8a0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
e8b0: 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
e8c0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
e8d0: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
e8e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
e8f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
e900: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
e910: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
e920: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
e930: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
e940: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e950: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
e960: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
e970: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
e980: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
e990: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
e9a0: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
e9b0: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
e9c0: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
e9d0: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
e9e0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
e9f0: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
ea00: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
ea10: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
ea20: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
ea30: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
ea40: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
ea50: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
ea60: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
ea70: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
ea80: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
ea90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
eaa0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
eab0: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
eac0: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
ead0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
eae0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
eaf0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
eb00: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
eb10: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
eb20: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
eb30: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
eb40: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
eb50: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
eb60: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
eb70: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
eb80: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
eb90: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
eba0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
ebb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
ebc0: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
ebd0: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
ebe0: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
ebf0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
ec00: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
ec10: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
ec20: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
ec30: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
ec40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
ec50: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
ec60: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
ec70: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
ec80: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
ec90: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
eca0: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
ecb0: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
ecc0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
ecd0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
ece0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
ecf0: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
ed00: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ed10: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
ed20: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
ed30: 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
ed40: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
ed50: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
ed60: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
ed70: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
ed80: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
ed90: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
eda0: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
edb0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
edc0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
edd0: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
ede0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
edf0: 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
ee00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
ee10: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
ee20: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
ee30: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
ee40: 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
ee50: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
ee60: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
ee70: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
ee80: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
ee90: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
eea0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
eeb0: 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
eec0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
eed0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
eee0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
eef0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
ef00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ef10: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
ef20: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
ef30: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
ef40: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
ef50: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
ef60: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
ef70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
ef80: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
ef90: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
efa0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
efb0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
efc0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
efd0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
efe0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
eff0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
f000: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f010: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
f020: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f030: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
f040: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
f050: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
f060: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
f070: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
f080: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
f090: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
f0a0: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
f0b0: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
f0c0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
f0d0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
f0e0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
f0f0: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
f100: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
f110: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
f120: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
f130: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
f140: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
f150: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
f160: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
f170: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
f180: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
f190: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
f1a0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
f1b0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
f1c0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
f1d0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
f1e0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
f1f0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
f200: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
f210: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f220: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
f230: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
f240: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
f250: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
f260: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
f270: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
f280: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
f290: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
f2a0: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
f2b0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
f2c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
f2d0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
f2e0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
f2f0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
f300: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
f310: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
f320: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
f330: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
f340: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
f350: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f360: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
f370: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
f380: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f390: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
f3a0: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
f3b0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
f3c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f3d0: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
f3e0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
f3f0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
f400: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
f410: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
f420: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
f430: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
f440: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
f450: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
f460: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
f470: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
f480: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
f490: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
f4a0: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
f4b0: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
f4c0: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
f4d0: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
f4e0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
f4f0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
f500: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
f510: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
f520: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
f530: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
f540: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
f550: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
f560: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f570: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
f580: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
f590: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
f5a0: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
f5b0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
f5c0: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
f5d0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
f5e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
f5f0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
f600: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
f610: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
f620: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
f630: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
f640: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
f650: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
f660: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
f670: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
f680: 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
f690: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
f6a0: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
f6b0: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
f6c0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
f6d0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
f6e0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
f6f0: 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
f700: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
f710: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
f720: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
f730: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
f740: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
f750: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
f760: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
f770: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
f780: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
f790: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
f7a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f7b0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
f7c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
f7d0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
f7e0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
f7f0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
f800: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
f810: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
f820: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
f830: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
f840: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
f850: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
f860: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
f870: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
f880: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
f890: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
f8a0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
f8b0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
f8c0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
f8d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
f8e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f8f0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
f900: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
f910: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
f920: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
f930: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
f940: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
f950: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
f960: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
f970: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
f980: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
f990: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
f9a0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
f9b0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
f9c0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
f9d0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
f9e0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
f9f0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
fa00: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
fa10: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fa20: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
fa30: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
fa40: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
fa50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
fa60: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
fa70: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
fa80: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
fa90: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
faa0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
fab0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
fac0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
fad0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
fae0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
faf0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
fb00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
fb10: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
fb20: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
fb30: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
fb40: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
fb50: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
fb60: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
fb70: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
fb80: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
fb90: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
fba0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
fbb0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
fbc0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
fbd0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
fbe0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
fbf0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
fc00: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
fc10: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
fc20: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
fc30: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
fc40: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
fc50: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
fc60: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
fc70: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
fc80: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
fc90: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
fca0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
fcb0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
fcc0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
fcd0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
fce0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
fcf0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
fd00: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
fd10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fd20: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
fd30: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
fd40: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
fd50: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
fd60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
fd70: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
fd80: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
fd90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
fda0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
fdb0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
fdc0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
fdd0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
fde0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
fdf0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
fe00: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
fe10: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
fe20: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
fe30: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
fe40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
fe50: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
fe60: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
fe70: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
fe80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
fe90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
fea0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
feb0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
fec0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
fed0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
fee0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
fef0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
ff00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
ff10: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
ff20: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
ff30: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
ff40: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
ff50: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
ff60: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
ff70: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
ff80: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
ff90: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
ffa0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
ffb0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
ffc0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
ffd0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
ffe0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
fff0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
10000 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
10010 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
10020 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
10030 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
10040 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
10050 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
10060 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
10070 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
10080 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
10090 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
100a0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
100b0 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
100c0 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
100d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
100e0 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
100f0 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
10100 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
10110 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10120 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
10130 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
10140 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10150 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
10160 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
10170 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
10180 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
10190 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
101a0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
101b0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
101c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
101d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
101e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
101f0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
10200 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
10210 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
10220 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
10230 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
10240 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
10250 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
10260 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
10270 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
10280 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
10290 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
102a0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
102b0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
102c0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
102d0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
102e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
102f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
10300 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
10310 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10320 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
10330 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
10340 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
10350 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
10360 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
10370 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
10380 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
10390 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
103a0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
103b0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
103c0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
103d0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
103e0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
103f0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10400 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10410 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
10420 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
10430 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
10440 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
10450 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
10460 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
10470 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
10480 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
10490 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
104a0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
104b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
104c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
104d0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
104e0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
104f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10500 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
10510 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
10520 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
10530 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
10540 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
10550 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
10560 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
10570 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10580 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
10590 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
105a0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
105b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
105c0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
105d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
105e0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
105f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10600 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
10610 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10620 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
10630 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10640 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10650 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10660 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10670 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10680 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
10690 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
106a0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
106b0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
106c0 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
106d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
106e0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
106f0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
10700 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
10710 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
10720 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
10730 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
10740 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10750 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
10760 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
10770 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
10780 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
10790 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
107a0 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
107b0 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
107c0 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
107d0 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
107e0 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
107f0 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
10800 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
10810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10820 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
10830 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
10840 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10850 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10860 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10870 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10880 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10890 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
108a0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
108b0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
108c0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
108d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
108e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
108f0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
10900 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
10910 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
10920 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
10930 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
10940 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
10950 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
10960 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10970 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
10980 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10990 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
109a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
109b0 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
109c0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
109d0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
109e0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
109f0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
10a00 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
10a10 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
10a20 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
10a30 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
10a40 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
10a50 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
10a60 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
10a70 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
10a80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10a90 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
10aa0 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
10ab0 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
10ac0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
10ad0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10ae0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10af0 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
10b00 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
10b10 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
10b20 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
10b30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10b40 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
10b50 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
10b60 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
10b70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
10b80 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
10b90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10ba0 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
10bb0 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
10bc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
10bd0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
10be0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
10bf0 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
10c00 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10c10 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10c20 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10c30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10c40 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10c50 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10c60 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
10c70 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
10c80 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
10c90 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
10ca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10cb0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
10cc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10cd0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
10ce0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
10cf0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
10d00 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10d10 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
10d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10d30 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
10d40 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
10d50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10d60 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10d70 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10d80 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10d90 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10da0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
10db0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10dc0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
10dd0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
10de0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
10df0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
10e00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10e10 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
10e20 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
10e30 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
10e40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10e50 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
10e60 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
10e70 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
10e80 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
10e90 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
10ea0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
10eb0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
10ec0 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
10ed0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10ee0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
10ef0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
10f00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10f10 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
10f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10f30 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
10f40 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10f50 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10f60 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10f70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10f80 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
10f90 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10fa0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10fb0 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
10fc0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10fd0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
10fe0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
10ff0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
11000 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
11010 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
11020 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
11030 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
11040 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
11050 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
11060 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
11070 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
11080 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
11090 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
110a0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
110b0 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
110c0 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
110d0 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
110e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
110f0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
11100 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11110 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
11120 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
11130 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
11140 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
11150 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
11160 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
11170 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
11180 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
11190 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
111a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
111b0 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
111c0 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
111d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
111e0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
111f0 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
11200 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
11210 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
11220 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
11230 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
11240 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
11250 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
11260 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11270 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
11280 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11290 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
112a0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
112b0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
112c0 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
112d0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
112e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
112f0 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
11300 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
11310 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
11320 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
11330 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
11340 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
11350 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
11360 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
11370 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
11380 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
11390 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
113a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
113b0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
113c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
113d0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
113e0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
113f0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
11400 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
11410 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
11420 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
11430 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
11440 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
11450 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
11460 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
11470 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
11480 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
11490 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
114a0 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
114b0 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
114c0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
114d0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
114e0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
114f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
11500 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
11510 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
11520 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
11530 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
11540 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
11550 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11560 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
11570 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
11580 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
11590 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
115a0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
115b0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
115c0 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
115d0 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
115e0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
115f0 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
11600 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
11610 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
11620 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
11630 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
11640 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11650 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
11660 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
11670 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
11680 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
11690 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
116a0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
116b0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
116c0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
116d0 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
116e0 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
116f0 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
11700 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
11710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
11720 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
11730 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
11740 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
11750 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11760 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11770 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
11780 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
11790 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
117a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
117b0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
117c0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
117d0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
117e0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
117f0 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
11800 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
11810 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
11820 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
11830 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
11840 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
11850 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
11860 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11870 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
11880 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
11890 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
118a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
118b0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a  PCACHE2 option..
118c0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
118d0 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
118e0 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
118f0 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
11900 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
11910 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
11920 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
11930 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
11940 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
11950 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
11960 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
11970 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
11980 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
11990 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
119a0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
119b0 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
119c0 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
119d0 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
119e0 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
119f0 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
11a00 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
11a10 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
11a20 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
11a30 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
11a40 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
11a50 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
11a60 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
11a70 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
11a80 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
11a90 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
11aa0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
11ab0 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
11ac0 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
11ad0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
11ae0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
11af0 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
11b00 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
11b10 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
11b20 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
11b30 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
11b40 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
11b50 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
11b60 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
11b70 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
11b80 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
11b90 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
11ba0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
11bb0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
11bc0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
11bd0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
11be0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11bf0 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
11c00 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
11c10 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  ce..** The point
11c20 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
11c30 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
11c40 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
11c50 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
11c60 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
11c70 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
11c80 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
11c90 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
11ca0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11cb0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
11cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
11cd0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
11ce0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
11cf0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
11d00 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
11d10 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
11d20 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
11d30 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
11d40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
11d50 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
11d60 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
11d70 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
11d80 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
11d90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
11da0 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
11db0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
11dc0 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
11dd0 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
11de0 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
11df0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
11e00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
11e10 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
11e20 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
11e30 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
11e40 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
11e50 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
11e60 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
11e70 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
11e80 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
11e90 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
11ea0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
11eb0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
11ec0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
11ed0 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
11ee0 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
11ef0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
11f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11f10 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
11f20 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
11f30 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
11f40 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
11f50 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
11f60 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
11f70 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
11f80 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
11f90 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
11fa0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
11fb0 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
11fc0 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
11fd0 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
11fe0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
11ff0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
12000 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
12010 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
12020 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
12030 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
12040 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
12050 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
12060 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
12070 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
12080 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12090 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
120a0 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
120b0 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
120c0 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
120d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
120e0 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
120f0 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
12100 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12110 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
12120 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12130 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12140 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12150 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12160 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12170 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
12180 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12190 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
121a0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
121b0 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
121c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
121d0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
121e0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
121f0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
12200 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
12210 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
12220 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12230 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
12240 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
12250 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  * content of the
12260 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
12270 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12280 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
12290 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
122a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
122b0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
122c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
122d0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
122e0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
122f0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12300 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12310 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
12320 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
12330 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
12340 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
12350 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
12360 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
12370 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12380 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
12390 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
123a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
123b0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
123c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
123d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
123e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
123f0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
12400 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
12410 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12420 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12430 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12440 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12450 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
12460 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12470 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
12480 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12490 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
124a0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
124b0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
124c0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
124d0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
124e0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
124f0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12500 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12510 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12520 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
12530 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
12540 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
12550 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
12560 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
12570 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
12580 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
12590 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
125a0 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
125b0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
125c0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
125d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
125e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
125f0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12600 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12610 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
12620 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
12630 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
12640 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
12650 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
12660 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12670 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
12680 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
12690 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
126a0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
126b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
126c0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
126d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
126e0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
126f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
12700 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
12710 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12720 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
12730 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
12740 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
12750 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
12760 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
12770 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
12780 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
12790 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
127a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
127b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
127c0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
127d0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
127e0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
127f0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
12800 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
12810 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
12820 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
12830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
12840 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
12850 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
12860 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
12870 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
12880 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
12890 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
128a0 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
128b0 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
128c0 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
128d0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
128e0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
128f0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
12900 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
12910 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12920 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
12930 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12940 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
12950 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12960 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12970 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12980 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12990 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
129a0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
129b0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
129c0 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
129d0 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
129e0 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
129f0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
12a00 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
12a10 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
12a20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
12a30 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
12a40 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
12a50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12a60 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
12a70 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12a80 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
12a90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12aa0 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
12ab0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12ac0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12ad0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12ae0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12af0 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
12b00 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
12b10 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
12b20 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
12b30 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
12b40 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12b50 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
12b60 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
12b70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12b80 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
12b90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
12ba0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
12bb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12bc0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
12bd0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
12be0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
12bf0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
12c00 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
12c10 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
12c20 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
12c30 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
12c40 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
12c50 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
12c60 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
12c70 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
12c80 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
12c90 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
12ca0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
12cb0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
12cc0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
12cd0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
12ce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
12cf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
12d00 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
12d10 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
12d20 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
12d30 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12d40 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
12d50 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
12d60 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
12d70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12d80 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
12d90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
12da0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
12db0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
12dc0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
12dd0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
12de0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
12df0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
12e00 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
12e10 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12e20 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
12e30 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
12e40 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
12e50 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
12e60 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
12e70 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
12e80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
12e90 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
12ea0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
12eb0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
12ec0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
12ed0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
12ee0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
12ef0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
12f00 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
12f10 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
12f20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
12f30 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
12f40 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
12f50 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
12f60 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
12f70 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
12f80 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
12f90 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
12fa0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
12fb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
12fc0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
12fd0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
12fe0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
12ff0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13000 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
13010 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13020 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
13030 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13040 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13050 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
13060 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
13070 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
13080 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
13090 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
130a0 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
130b0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
130c0 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
130d0 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
130e0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
130f0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
13100 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
13110 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
13120 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
13130 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
13140 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
13150 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
13160 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
13170 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
13180 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
13190 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
131a0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
131b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
131c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
131d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
131e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
131f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
13200 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
13210 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
13220 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
13230 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
13240 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
13250 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
13260 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
13270 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
13280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13290 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
132a0 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
132b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
132c0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
132d0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
132e0 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
132f0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
13300 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
13310 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
13320 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b  defined..**.** [
13330 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
13340 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13350 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
13360 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
13370 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
13380 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
13390 61 6b 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  aks a single int
133a0 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
133b0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
133c0 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
133d0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
133e0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
133f0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
13400 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
13410 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
13420 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
13430 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68  y optimizer.  Th
13440 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
13450 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
13460 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
13470 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
13480 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
13490 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
134a0 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
134b0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
134c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
134d0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
134e0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
134f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
13500 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
13510 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
13520 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
13530 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
13540 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
13550 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
13560 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
13570 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65   malfunction whe
13580 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
13590 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
135a0 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
135b0 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
135c0 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
135d0 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
135e0 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
135f0 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
13600 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
13610 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
13620 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
13630 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
13640 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13650 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
13660 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13670 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
13680 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13690 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
136a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
136b0 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
136c0 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
136d0 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
136e0 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
136f0 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
13700 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
13710 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
13720 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
13730 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
13740 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
13750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
13760 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
13770 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
13780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13790 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
137a0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
137b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
137c0 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
137d0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
137e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
137f0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
13800 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
13810 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
13820 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13830 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
13840 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
13850 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
13860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13870 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
13880 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
13890 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
138a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
138b0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
138c0 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
138d0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
138e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
138f0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
13900 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
13910 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
13920 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
13930 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13940 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
13950 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
13960 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13970 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
13980 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
13990 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
139a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
139b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
139c0 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
139d0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
139e0 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
139f0 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
13a00 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
13a10 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
13a20 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
13a30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13a40 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
13a50 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
13a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13a70 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
13a80 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
13a90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13aa0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13ab0 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
13ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13ad0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
13ae0 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
13af0 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
13b00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13b10 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
13b20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
13b30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13b40 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
13b50 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
13b60 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
13b70 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
13b80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13b90 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
13ba0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13bb0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
13bc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13bd0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
13be0 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
13bf0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
13c00 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
13c10 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
13c20 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
13c30 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
13c40 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
13c50 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
13c60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c70 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
13c80 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
13c90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13ca0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
13cb0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
13cc0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
13cd0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
13ce0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
13cf0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13d00 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
13d10 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
13d20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13d30 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
13d40 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
13d50 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
13d60 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
13d70 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
13d80 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13d90 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
13da0 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
13db0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
13dc0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
13dd0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
13de0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
13df0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
13e00 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
13e10 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
13e20 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
13e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
13e40 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
13e50 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
13e60 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13e70 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
13e80 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
13e90 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
13ea0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
13eb0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
13ec0 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
13ed0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
13ee0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
13ef0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
13f00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13f10 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
13f20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
13f30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
13f40 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
13f50 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
13f60 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
13f70 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
13f80 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
13f90 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
13fa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13fb0 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
13fc0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13fd0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
13fe0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
13ff0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
14000 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
14010 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
14020 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
14030 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
14040 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
14050 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
14060 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
14070 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
14080 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
14090 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
140a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
140b0 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
140c0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
140d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
140e0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
140f0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
14100 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
14110 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
14120 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
14130 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
14140 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
14150 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
14160 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
14170 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
14180 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
14190 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
141a0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
141b0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
141c0 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
141d0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
141e0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
141f0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
14200 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
14210 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
14220 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
14230 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
14240 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
14250 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
14260 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
14270 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
14280 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
14290 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
142a0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
142b0 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
142c0 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
142d0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
142e0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
142f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14300 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
14310 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
14320 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
14330 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
14340 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
14350 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
14360 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
14370 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
14380 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
14390 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
143a0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
143b0 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
143c0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
143d0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
143e0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
143f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
14400 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
14410 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
14420 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
14430 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
14440 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
14450 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
14460 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
14470 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
14480 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
14490 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
144a0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
144b0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
144c0 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
144d0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
144e0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
144f0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
14500 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
14510 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
14520 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14530 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14540 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
14550 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
14560 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
14570 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
14580 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
14590 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
145a0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
145b0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
145c0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
145d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
145e0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
145f0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
14600 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
14610 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
14620 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
14630 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
14640 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
14650 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14660 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
14670 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
14680 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
14690 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
146a0 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
146b0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
146c0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
146d0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
146e0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
146f0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
14700 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
14710 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
14720 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
14730 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
14740 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
14750 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
14760 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
14770 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
14780 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
14790 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
147a0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
147b0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
147c0 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
147d0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
147e0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
147f0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
14800 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
14810 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
14820 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
14830 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
14840 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
14850 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
14860 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
14870 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
14880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
14890 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
148a0 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
148b0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
148c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
148d0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
148e0 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
148f0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
14900 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
14910 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
14920 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
14930 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
14940 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
14950 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
14960 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
14970 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
14980 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
14990 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
149a0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
149b0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
149c0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
149d0 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
149e0 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
149f0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
14a00 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
14a10 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
14a20 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
14a30 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
14a40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
14a50 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
14a60 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
14a70 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
14a80 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
14a90 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
14aa0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
14ab0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
14ac0 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
14ad0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
14ae0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
14af0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
14b00 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
14b10 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
14b20 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
14b30 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
14b40 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
14b50 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
14b60 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
14b70 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
14b80 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
14b90 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
14ba0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
14bb0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
14bc0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
14bd0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
14be0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
14bf0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
14c00 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
14c10 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
14c20 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
14c30 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
14c40 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
14c50 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
14c60 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
14c70 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
14c80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
14c90 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
14ca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
14cb0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
14cc0 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53  ument.  ^As of S
14cd0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
14ce0 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  7.7, this routin
14cf0 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68  es.** records th
14d00 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
14d10 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69  wid of both ordi
14d20 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20  nary tables and 
14d30 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
14d40 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
14d50 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
14d60 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
14d70 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
14d80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14d90 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
14da0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
14db0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
14dc0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
14dd0 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
14de0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
14df0 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
14e00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
14e10 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
14e20 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
14e30 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
14e40 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
14e50 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
14e60 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
14e70 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
14e80 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
14e90 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
14ea0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
14eb0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
14ec0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
14ed0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
14ee0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
14ef0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
14f00 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
14f10 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
14f20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
14f30 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
14f40 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
14f50 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
14f60 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
14f70 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
14f80 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
14f90 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
14fa0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
14fb0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
14fc0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
14fd0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
14fe0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
14ff0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
15000 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
15010 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
15020 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
15030 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
15040 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
15050 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
15060 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
15070 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
15080 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
15090 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
150a0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
150b0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
150c0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
150d0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
150e0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
150f0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
15100 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
15110 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
15120 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
15130 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
15140 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
15150 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
15160 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
15170 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
15180 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
15190 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
151a0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
151b0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
151c0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
151d0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
151e0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
151f0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
15200 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
15210 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
15220 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
15230 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
15240 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
15250 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
15260 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
15270 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
15280 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
15290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
152a0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
152b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
152c0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
152d0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
152e0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
152f0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
15300 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
15310 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15320 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
15330 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
15340 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
15350 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
15360 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
15370 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
15380 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
15390 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
153a0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
153b0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
153c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
153d0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
153e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
153f0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
15400 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
15410 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
15420 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
15430 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
15440 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
15450 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
15460 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
15470 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
15480 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
15490 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
154a0 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
154b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
154c0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
154d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
154e0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
154f0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
15500 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
15510 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
15520 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
15530 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
15540 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
15550 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
15560 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
15570 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
15580 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
15590 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
155a0 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
155b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
155c0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
155d0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
155e0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
155f0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
15600 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
15610 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
15620 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
15630 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
15640 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
15650 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
15660 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
15670 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
15680 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
15690 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
156a0 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
156b0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
156c0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
156d0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
156e0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
156f0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
15700 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
15710 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
15720 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
15730 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
15740 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
15750 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
15760 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
15770 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
15780 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
15790 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
157a0 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
157b0 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
157c0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
157d0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
157e0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
157f0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
15800 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
15810 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
15820 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
15830 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
15840 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
15850 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
15860 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
15870 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
15880 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
15890 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
158a0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
158b0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
158c0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
158d0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
158e0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
158f0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
15900 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
15910 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
15920 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
15930 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
15940 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
15950 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
15960 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
15970 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
15980 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
15990 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
159a0 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
159b0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
159c0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
159d0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
159e0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
159f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
15a00 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
15a10 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
15a20 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
15a30 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
15a40 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
15a50 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
15a60 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
15a70 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
15a80 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
15a90 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
15aa0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
15ab0 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
15ac0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
15ad0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
15ae0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
15af0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
15b00 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
15b10 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
15b20 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
15b30 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
15b40 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
15b50 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
15b60 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
15b70 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
15b80 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
15b90 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
15ba0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
15bb0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
15bc0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
15bd0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
15be0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
15bf0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
15c00 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
15c10 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
15c20 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
15c30 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
15c40 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
15c50 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
15c60 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
15c70 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
15c80 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
15c90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
15ca0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
15cb0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
15cc0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
15cd0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
15ce0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
15cf0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
15d00 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
15d10 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
15d20 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
15d30 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
15d40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15d50 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
15d60 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
15d70 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
15d80 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
15d90 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
15da0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
15db0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
15dc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
15dd0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
15de0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
15df0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
15e00 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
15e10 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
15e20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
15e30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
15e40 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
15e50 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
15e60 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
15e70 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
15e80 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
15e90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
15ea0 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
15eb0 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
15ec0 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
15ed0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15ee0 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
15ef0 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
15f00 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
15f10 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15f20 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
15f30 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
15f40 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
15f50 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
15f60 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
15f70 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
15f80 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
15f90 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
15fa0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
15fb0 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
15fc0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
15fd0 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
15fe0 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
15ff0 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
16000 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
16010 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
16020 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
16030 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
16040 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
16050 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
16060 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
16070 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
16080 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
16090 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
160a0 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
160b0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
160c0 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
160d0 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
160e0 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
160f0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
16100 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
16110 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
16120 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
16130 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
16140 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
16150 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
16160 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
16170 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
16180 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
16190 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
161a0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
161b0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
161c0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
161d0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
161e0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
161f0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
16200 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
16210 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
16220 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16230 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
16240 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
16250 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
16260 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
16270 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
16280 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
16290 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
162a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
162b0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
162c0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
162d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
162e0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
162f0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
16300 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
16310 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
16320 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
16330 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
16340 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
16350 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
16360 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
16370 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
16380 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
16390 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
163a0 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
163b0 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
163c0 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
163d0 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
163e0 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
163f0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
16400 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
16410 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
16420 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
16430 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
16440 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
16450 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
16460 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
16470 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
16480 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
16490 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
164a0 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
164b0 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
164c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
164d0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
164e0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
164f0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
16500 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
16510 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
16520 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
16530 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
16540 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
16550 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
16560 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
16570 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
16580 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
16590 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
165a0 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
165b0 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
165c0 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
165d0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
165e0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
165f0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
16600 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
16610 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
16620 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
16630 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
16640 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
16650 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
16660 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
16670 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
16680 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
16690 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
166a0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
166b0 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
166c0 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
166d0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
166e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
166f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16700 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
16710 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
16720 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
16730 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
16740 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
16750 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
16760 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
16770 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
16780 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
16790 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
167a0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
167b0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
167c0 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
167d0 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
167e0 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
167f0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
16800 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
16810 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
16820 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
16830 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
16840 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
16850 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
16860 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
16870 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
16880 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
16890 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
168a0 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
168b0 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
168c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
168d0 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
168e0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
168f0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
16900 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
16910 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
16920 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16930 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
16940 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
16950 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
16960 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
16970 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
16980 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
16990 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
169a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
169b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
169c0 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
169d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
169e0 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
169f0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
16a00 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
16a10 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
16a20 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
16a30 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
16a40 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
16a50 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
16a60 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
16a70 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
16a80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
16a90 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
16aa0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
16ab0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
16ac0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
16ad0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
16ae0 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
16af0 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
16b00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
16b10 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
16b20 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
16b30 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
16b40 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
16b50 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
16b60 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
16b70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
16b80 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
16b90 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
16ba0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
16bb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
16bc0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
16bd0 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
16be0 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
16bf0 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
16c00 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
16c10 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
16c20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
16c30 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
16c40 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
16c50 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
16c60 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
16c70 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
16c80 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
16c90 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
16ca0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
16cb0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
16cc0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
16cd0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
16ce0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
16cf0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
16d00 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
16d10 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
16d20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
16d30 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
16d40 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
16d50 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
16d60 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
16d70 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
16d80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
16d90 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
16da0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
16db0 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
16dc0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
16dd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
16de0 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
16df0 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
16e00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
16e10 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
16e20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
16e30 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
16e40 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
16e50 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
16e60 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
16e70 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
16e80 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
16e90 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
16ea0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
16eb0 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
16ec0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
16ed0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
16ee0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
16ef0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
16f00 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
16f10 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
16f20 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
16f30 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
16f40 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
16f50 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
16f60 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
16f70 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
16f80 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
16f90 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
16fa0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16fb0 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
16fc0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
16fd0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
16fe0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
16ff0 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
17000 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
17010 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
17020 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
17030 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
17040 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
17050 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
17060 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
17070 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
17080 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
17090 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
170a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
170b0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
170c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
170d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
170e0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
170f0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
17100 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
17110 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
17120 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
17130 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
17140 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
17150 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
17160 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
17170 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
17180 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
17190 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
171a0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
171b0 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
171c0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
171d0 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
171e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
171f0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
17200 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
17210 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
17220 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17230 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
17240 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
17250 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
17260 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
17270 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
17280 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
17290 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
172a0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
172b0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
172c0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
172d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
172e0 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
172f0 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
17300 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
17310 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
17320 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
17330 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
17340 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
17350 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
17360 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
17370 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
17380 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
17390 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
173a0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
173b0 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
173c0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
173d0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
173e0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
173f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17400 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
17410 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
17420 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
17430 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
17440 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
17450 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
17460 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
17470 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
17480 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
17490 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
174a0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
174b0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
174c0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
174d0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
174e0 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
174f0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
17500 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
17510 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
17520 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
17530 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
17540 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
17550 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
17560 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
17570 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
17580 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
17590 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
175a0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
175b0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
175c0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
175d0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
175e0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
175f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
17600 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
17610 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
17620 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
17630 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
17640 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
17650 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
17660 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
17670 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
17680 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
17690 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
176a0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
176b0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
176c0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
176d0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
176e0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
176f0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
17700 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
17710 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
17720 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
17730 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
17740 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
17750 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
17760 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
17770 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
17780 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
17790 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
177a0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
177b0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
177c0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
177d0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
177e0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
177f0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
17800 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
17810 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
17820 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
17830 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
17840 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
17850 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
17860 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
17870 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
17880 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
17890 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
178a0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
178b0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
178c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
178d0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
178e0 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
178f0 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
17900 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
17910 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
17920 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
17930 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
17940 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
17950 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
17960 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
17970 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
17980 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
17990 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
179a0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
179b0 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
179c0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
179d0 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
179e0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
179f0 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
17a00 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
17a10 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
17a20 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
17a30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
17a40 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
17a50 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
17a60 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
17a70 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
17a80 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
17a90 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
17aa0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
17ab0 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
17ac0 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
17ad0 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
17ae0 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
17af0 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
17b00 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
17b10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
17b20 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
17b30 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
17b40 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
17b50 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
17b60 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
17b70 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
17b80 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
17b90 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
17ba0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
17bb0 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
17bc0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
17bd0 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
17be0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
17bf0 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
17c00 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
17c10 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
17c20 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
17c30 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
17c40 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
17c50 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
17c60 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
17c70 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
17c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17c90 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
17ca0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
17cb0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
17cc0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
17cd0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
17ce0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
17cf0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
17d00 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
17d10 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
17d20 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
17d30 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
17d40 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
17d50 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
17d60 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
17d70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
17d80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
17d90 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
17da0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
17db0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
17dc0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
17dd0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
17de0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
17df0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
17e00 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
17e10 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
17e20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
17e30 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
17e40 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
17e50 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
17e60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
17e70 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
17e80 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
17e90 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
17ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17eb0 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
17ec0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
17ed0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
17ee0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
17ef0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
17f00 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
17f10 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
17f20 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
17f30 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
17f40 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
17f50 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
17f60 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
17f70 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
17f80 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
17f90 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
17fa0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
17fb0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
17fc0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
17fd0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
17fe0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
17ff0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
18000 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
18010 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18020 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
18030 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
18040 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
18050 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
18060 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
18070 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
18080 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
18090 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
180a0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
180b0 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
180c0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
180d0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
180e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
180f0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
18100 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18110 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
18120 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
18130 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
18140 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
18150 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
18160 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18170 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
18180 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
18190 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
181a0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
181b0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
181c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
181d0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
181e0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
181f0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
18200 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
18210 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
18220 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
18230 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
18240 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
18250 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
18260 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
18270 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
18280 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
18290 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
182a0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
182b0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
182c0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
182d0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
182e0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
182f0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
18300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
18310 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
18320 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
18330 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
18340 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
18350 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
18360 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
18370 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
18380 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
18390 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
183a0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
183b0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
183c0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
183d0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
183e0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
183f0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
18400 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
18410 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
18420 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
18430 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
18440 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
18450 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
18460 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
18470 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
18480 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
18490 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
184a0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
184b0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
184c0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
184d0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
184e0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
184f0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
18500 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
18510 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
18520 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
18530 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
18540 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
18550 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
18560 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
18570 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
18580 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
18590 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
185a0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
185b0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
185c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
185d0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
185e0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
185f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
18600 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
18610 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
18620 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
18630 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
18640 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18650 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
18660 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
18670 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
18680 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
18690 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
186a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
186b0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
186c0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
186d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
186e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
186f0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
18700 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
18710 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
18720 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
18730 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
18740 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18750 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
18760 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
18770 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
18780 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18790 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
187a0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
187b0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
187c0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
187d0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
187e0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
187f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
18800 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
18810 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
18820 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
18830 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
18840 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
18850 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
18860 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
18870 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
18880 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
18890 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
188a0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
188b0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
188c0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
188d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
188e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
188f0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
18900 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
18910 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
18920 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
18930 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
18940 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
18950 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
18960 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
18970 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18980 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
18990 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
189a0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
189b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
189c0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
189d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
189e0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
189f0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
18a00 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
18a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18a20 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
18a30 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
18a40 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
18a50 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
18a60 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
18a70 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
18a80 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
18a90 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
18aa0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
18ab0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
18ac0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
18ad0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
18ae0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
18af0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
18b00 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
18b10 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
18b20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
18b30 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
18b40 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
18b50 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
18b60 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
18b70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
18b80 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
18b90 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
18ba0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
18bb0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
18bc0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
18bd0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
18be0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
18bf0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
18c00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
18c10 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
18c20 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
18c30 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
18c40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
18c50 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
18c60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
18c70 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
18c80 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
18c90 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
18ca0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
18cb0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
18cc0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
18cd0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
18ce0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
18cf0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
18d00 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
18d10 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
18d20 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
18d30 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
18d40 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
18d50 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
18d60 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
18d70 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
18d80 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
18d90 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
18da0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
18db0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
18dc0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
18dd0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
18de0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
18df0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
18e00 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
18e10 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
18e20 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
18e30 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
18e40 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
18e50 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
18e60 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
18e70 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
18e80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
18e90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
18ea0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
18eb0 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
18ec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
18ed0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
18ee0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
18ef0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
18f00 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
18f10 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
18f20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
18f30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
18f40 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
18f50 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
18f60 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
18f70 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
18f80 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
18f90 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
18fa0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
18fb0 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
18fc0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
18fd0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
18fe0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
18ff0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
19000 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
19010 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19020 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
19030 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
19040 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
19050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
19060 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
19070 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
19080 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
19090 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
190a0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
190b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
190c0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
190d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
190e0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
190f0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
19100 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
19110 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
19120 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
19130 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
19140 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
19150 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
19160 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
19170 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
19180 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
19190 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
191a0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
191b0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
191c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
191d0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
191e0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
191f0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
19200 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
19210 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
19220 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
19230 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
19240 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
19250 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
19260 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
19270 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
19280 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
19290 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
192a0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
192b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
192c0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
192d0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
192e0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
192f0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
19300 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
19310 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
19320 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
19330 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
19340 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
19350 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
19360 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
19370 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
19380 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
19390 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
193a0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
193b0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
193c0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
193d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
193e0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
193f0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
19400 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
19410 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
19420 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
19430 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
19440 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
19450 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
19460 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
19470 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
19480 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
19490 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
194a0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
194b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
194c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
194d0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
194e0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
194f0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
19500 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
19510 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
19520 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
19530 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
19540 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
19550 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
19560 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
19570 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
19580 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
19590 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
195a0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
195b0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
195c0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
195d0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
195e0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
195f0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
19600 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
19610 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
19620 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
19630 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
19640 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
19650 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
19660 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
19670 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
19680 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
19690 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
196a0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
196b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
196c0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
196d0 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
196e0 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
196f0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
19700 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
19710 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
19720 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
19730 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
19740 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
19750 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
19760 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
19770 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
19780 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
19790 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
197a0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
197b0 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
197c0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
197d0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
197e0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
197f0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
19800 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
19810 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
19820 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
19830 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
19840 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
19850 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
19860 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
19870 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
19880 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
19890 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
198a0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
198b0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
198c0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
198d0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
198e0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
198f0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
19900 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
19910 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
19920 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
19930 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
19940 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19950 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
19960 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
19970 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
19980 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
19990 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
199a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
199b0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
199c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
199d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
199e0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
199f0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
19a00 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
19a10 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
19a20 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
19a30 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
19a40 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
19a50 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
19a60 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
19a70 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
19a80 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
19a90 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
19aa0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
19ab0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
19ac0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
19ad0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
19ae0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
19af0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
19b00 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
19b10 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19b20 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19b30 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
19b40 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
19b50 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
19b60 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
19b70 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
19b80 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
19b90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
19ba0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
19bb0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
19bc0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
19bd0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
19be0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
19bf0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
19c00 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
19c10 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
19c20 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
19c30 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
19c40 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
19c50 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
19c60 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
19c70 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
19c80 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
19c90 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
19ca0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
19cb0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
19cc0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
19cd0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
19ce0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
19cf0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
19d00 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
19d10 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
19d20 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
19d30 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
19d40 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
19d50 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
19d60 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
19d70 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
19d80 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
19d90 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
19da0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
19db0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
19dc0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
19dd0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
19de0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
19df0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
19e00 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
19e10 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
19e20 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
19e30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
19e40 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
19e50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
19e60 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
19e70 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
19e80 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
19e90 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
19ea0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
19eb0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
19ec0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
19ed0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
19ee0 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
19ef0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
19f00 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
19f10 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
19f20 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
19f30 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
19f40 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
19f50 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
19f60 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
19f70 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
19f80 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
19f90 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
19fa0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
19fb0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
19fc0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
19fd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
19fe0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
19ff0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1a000 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1a010 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1a020 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1a030 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1a040 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1a050 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1a060 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1a070 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1a080 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1a090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1a0a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1a0b0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1a0c0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1a0d0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1a0e0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1a0f0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1a100 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1a110 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1a120 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1a130 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1a140 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1a150 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1a160 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1a170 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1a180 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1a190 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1a1a0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1a1b0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1a1c0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1a1d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a1e0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1a1f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1a200 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1a210 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1a220 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1a230 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1a240 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1a250 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1a260 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1a270 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1a280 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1a290 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1a2a0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1a2b0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1a2c0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1a2d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1a2e0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1a2f0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1a300 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1a310 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1a320 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1a330 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1a340 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1a350 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1a360 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1a370 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1a380 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a390 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1a3a0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1a3b0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1a3c0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1a3d0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1a3e0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1a3f0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1a400 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1a410 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1a420 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1a430 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1a440 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1a450 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1a460 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1a470 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1a480 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1a490 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1a4a0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1a4b0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1a4c0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1a4d0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1a4e0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1a4f0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1a500 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1a510 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1a520 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1a530 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1a540 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1a550 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1a560 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1a570 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1a580 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1a590 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1a5a0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1a5b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1a5c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1a5d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1a5e0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1a5f0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1a600 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1a610 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1a620 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1a630 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1a640 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a650 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1a660 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1a670 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1a680 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1a690 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1a6a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1a6b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1a6c0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1a6d0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1a6e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1a6f0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1a700 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1a710 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1a720 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1a730 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1a740 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1a750 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1a760 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1a770 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1a780 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1a790 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1a7a0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1a7b0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1a7c0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1a7d0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1a7e0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1a7f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1a800 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1a810 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1a820 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1a830 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1a840 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1a850 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1a860 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1a870 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1a880 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1a890 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1a8a0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1a8b0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1a8c0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1a8d0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1a8e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1a8f0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1a900 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1a910 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1a920 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1a930 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1a940 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1a950 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1a960 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1a970 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1a980 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1a990 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1a9a0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1a9b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1a9c0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1a9d0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1a9e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1a9f0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1aa00 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1aa10 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1aa20 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1aa30 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1aa40 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1aa50 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1aa60 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1aa70 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1aa80 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1aa90 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1aaa0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1aab0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1aac0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1aad0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1aae0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1aaf0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1ab00 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1ab10 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1ab20 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1ab30 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1ab40 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1ab50 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1ab60 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1ab70 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1ab80 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1ab90 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1aba0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1abb0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1abc0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1abd0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1abe0 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1abf0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1ac00 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1ac10 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1ac20 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1ac30 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1ac40 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1ac50 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1ac60 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1ac70 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1ac80 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1ac90 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1aca0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1acb0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1acc0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1acd0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1ace0 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1acf0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1ad00 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1ad10 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1ad20 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1ad30 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1ad40 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1ad50 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1ad60 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1ad70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ad80 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1ad90 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1ada0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1adb0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1adc0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1add0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1ade0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1adf0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1ae00 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1ae10 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1ae20 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1ae30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1ae40 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1ae50 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1ae60 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1ae70 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1ae80 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1ae90 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1aea0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1aeb0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1aec0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1aed0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
1aee0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
1aef0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1af00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1af10 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
1af20 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1af30 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
1af40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1af50 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1af60 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1af70 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1af80 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1af90 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1afa0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1afb0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1afc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1afd0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1afe0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1aff0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1b000 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1b010 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1b020 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b030 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1b040 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1b050 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1b060 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1b070 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1b080 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1b090 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1b0a0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1b0b0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1b0c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1b0d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1b0e0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1b0f0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1b100 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1b110 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1b120 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1b130 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1b140 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1b150 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1b160 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1b170 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1b180 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1b190 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1b1a0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1b1b0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1b1c0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1b1d0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1b1e0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1b1f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1b200 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1b210 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1b220 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1b230 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1b240 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1b250 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1b260 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1b270 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1b280 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1b290 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1b2a0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1b2b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1b2c0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1b2d0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1b2e0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1b2f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1b300 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1b310 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1b320 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1b330 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1b340 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1b350 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1b360 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1b370 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
1b380 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1b390 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1b3a0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53  ry_used(void);.S
1b3b0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1b3c0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1b3d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1b3e0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1b3f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b400 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1b410 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1b420 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1b430 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1b440 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1b450 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1b460 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1b470 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1b480 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1b490 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1b4a0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1b4b0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1b4c0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1b4d0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1b4e0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1b4f0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1b500 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1b510 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1b520 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1b530 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1b540 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1b550 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1b560 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1b570 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1b580 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1b590 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1b5a0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1b5b0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1b5c0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1b5d0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1b5e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1b5f0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
1b600 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
1b610 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
1b620 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
1b630 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
1b640 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1b650 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1b660 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
1b670 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1b680 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1b690 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1b6a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1b6b0 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
1b6c0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
1b6d0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1b6e0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1b6f0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1b700 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1b710 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1b720 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1b730 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1b740 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
1b750 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
1b760 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1b770 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1b780 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1b790 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1b7a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1b7b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1b7c0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1b7d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b7e0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1b7f0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1b800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1b810 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1b820 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1b830 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1b840 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1b850 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1b860 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1b870 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1b880 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1b890 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1b8a0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1b8b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1b8c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1b8d0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1b8e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b8f0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1b900 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1b910 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1b920 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1b930 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1b940 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1b950 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1b960 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1b970 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1b980 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1b990 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1b9a0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1b9b0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1b9c0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1b9d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1b9e0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1b9f0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1ba00 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1ba10 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1ba20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1ba30 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1ba40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1ba50 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1ba60 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1ba70 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1ba80 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1ba90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1baa0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1bab0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1bac0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1bad0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1bae0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1baf0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1bb00 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1bb10 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1bb20 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1bb30 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1bb40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1bb50 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1bb60 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1bb70 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1bb80 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1bb90 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1bba0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1bbb0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1bbc0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1bbd0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1bbe0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1bbf0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1bc00 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1bc10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1bc20 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1bc30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1bc40 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1bc50 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1bc60 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1bc70 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1bc80 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1bc90 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1bca0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1bcb0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1bcc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1bcd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1bce0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1bcf0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1bd00 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1bd10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1bd20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1bd30 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1bd40 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1bd50 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1bd60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1bd70 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1bd80 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1bd90 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1bda0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1bdb0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1bdc0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1bdd0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1bde0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1bdf0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1be00 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1be10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1be20 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1be30 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1be40 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1be50 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1be60 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1be70 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1be80 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1be90 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1bea0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1beb0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1bec0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1bed0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1bee0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1bef0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1bf00 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1bf10 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1bf20 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1bf30 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1bf40 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1bf50 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1bf60 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1bf70 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1bf80 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1bf90 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1bfa0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1bfb0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1bfc0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1bfd0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1bfe0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1bff0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1c000 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1c010 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1c020 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1c030 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1c040 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1c050 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1c060 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1c070 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1c080 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1c090 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1c0a0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1c0b0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1c0c0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1c0d0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1c0e0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1c0f0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1c100 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1c110 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1c120 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1c130 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1c140 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1c150 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1c160 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1c170 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1c180 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1c190 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1c1a0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1c1b0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1c1c0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1c1d0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1c1e0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1c1f0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1c200 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1c210 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1c220 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1c230 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1c240 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1c250 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1c260 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1c270 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1c280 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1c290 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1c2a0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1c2b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1c2c0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1c2d0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1c2e0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1c2f0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1c300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1c310 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1c320 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1c330 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1c340 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1c350 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1c360 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1c370 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1c380 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1c390 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1c3a0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1c3b0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1c3c0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1c3d0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1c3e0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1c3f0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1c400 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1c410 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1c420 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1c430 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1c440 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1c450 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1c460 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1c470 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1c480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c490 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1c4a0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1c4b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1c4c0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1c4d0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1c4e0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1c4f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c500 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1c510 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1c520 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1c530 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1c540 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1c550 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c560 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1c570 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1c580 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1c590 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c5a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c5b0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1c5c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1c5d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1c5e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c5f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1c600 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1c610 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1c620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1c630 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1c640 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1c650 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1c660 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1c670 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c680 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1c690 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1c6a0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1c6b0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1c6c0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1c6d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c6e0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1c6f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1c700 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1c710 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1c720 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1c730 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1c740 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1c750 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1c760 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1c770 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1c780 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1c790 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c7a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1c7b0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1c7c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1c7d0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1c7e0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1c7f0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1c800 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1c810 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1c820 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1c830 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1c840 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1c850 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1c860 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1c870 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1c880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c890 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1c8a0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1c8b0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1c8c0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1c8d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
1c8e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1c8f0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1c900 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1c910 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1c920 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1c930 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1c940 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1c950 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1c960 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1c970 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1c980 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1c990 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1c9a0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1c9b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c9c0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1c9d0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1c9e0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1c9f0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1ca00 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1ca10 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1ca20 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ca30 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1ca40 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1ca50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1ca60 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1ca70 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1ca80 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1ca90 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1caa0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1cab0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1cac0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1cad0 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1cae0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1caf0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1cb00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1cb10 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1cb20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1cb30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1cb40 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1cb50 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1cb60 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1cb70 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1cb80 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1cb90 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1cba0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1cbb0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1cbc0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1cbd0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1cbe0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1cbf0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1cc00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1cc10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1cc20 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1cc30 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1cc40 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1cc50 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1cc60 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1cc70 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1cc80 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1cc90 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1cca0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1ccb0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1ccc0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1ccd0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1cce0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1ccf0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1cd00 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1cd10 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1cd20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1cd30 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1cd40 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1cd50 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1cd60 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1cd70 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1cd80 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1cd90 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1cda0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1cdb0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1cdc0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1cdd0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1cde0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1cdf0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1ce00 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1ce10 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1ce20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1ce30 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1ce40 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1ce50 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1ce60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1ce70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1ce80 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1ce90 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1cea0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1ceb0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1cec0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1ced0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cee0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1cef0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1cf00 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1cf10 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1cf20 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1cf30 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1cf40 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1cf50 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1cf60 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1cf70 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1cf80 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1cf90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1cfa0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1cfb0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1cfc0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1cfd0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1cfe0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1cff0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1d000 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1d010 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1d020 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d030 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1d040 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1d050 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d060 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1d070 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d080 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1d090 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1d0a0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1d0b0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1d0c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d0d0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1d0e0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1d0f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1d100 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1d110 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d120 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1d130 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1d140 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1d150 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1d160 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d170 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1d180 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1d190 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1d1a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d1b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d1c0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1d1d0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1d1e0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1d1f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d210 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1d220 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1d230 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1d240 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d250 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d260 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1d270 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1d280 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1d290 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d2a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d2b0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1d2c0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1d2d0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1d2e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d2f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d300 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1d310 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1d320 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1d330 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1d350 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1d360 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1d370 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1d380 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1d390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1d3a0 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1d3b0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1d3c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1d3d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d3e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d3f0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1d400 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1d410 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1d420 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d430 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d440 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1d450 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1d460 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1d470 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d480 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1d490 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1d4a0 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1d4b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1d4c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1d4d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1d4e0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1d4f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1d500 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d510 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d520 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1d530 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1d540 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d550 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1d560 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d570 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1d580 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1d590 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1d5a0 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1d5b0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1d5c0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1d5d0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1d5e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1d5f0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1d600 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d610 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1d620 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1d630 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1d640 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d650 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d660 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1d670 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1d680 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1d690 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d6a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d6b0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1d6c0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1d6d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d6e0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1d6f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d700 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1d710 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1d720 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1d730 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d750 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1d760 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1d770 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1d780 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d7a0 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1d7b0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1d7c0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1d7d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d7e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1d7f0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1d800 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1d810 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1d820 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1d840 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1d850 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1d860 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d870 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d890 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1d8a0 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1d8b0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1d8c0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1d8d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d8e0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1d8f0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1d900 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1d910 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1d920 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1d930 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1d940 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1d950 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1d960 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1d970 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1d980 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1d990 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1d9a0 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1d9b0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1d9c0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1d9d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1d9e0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1d9f0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1da00 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1da10 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1da20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1da30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1da40 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1da50 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1da60 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1da70 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1da80 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1da90 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1daa0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1dab0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1dac0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1dad0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1dae0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1daf0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1db00 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1db10 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1db20 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1db30 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1db40 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1db50 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1db60 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1db70 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1db80 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1db90 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1dba0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1dbb0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1dbc0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1dbd0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1dbe0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1dbf0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1dc00 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1dc10 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1dc20 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1dc30 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1dc40 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1dc50 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1dc60 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1dc70 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1dc80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1dc90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1dca0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1dcb0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1dcc0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1dcd0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1dce0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1dcf0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1dd00 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1dd10 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1dd20 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1dd30 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1dd40 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1dd50 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1dd60 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1dd70 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1dd80 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1dd90 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1dda0 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1ddb0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1ddc0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1ddd0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1dde0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1ddf0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1de00 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1de10 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1de20 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1de30 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1de40 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1de50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1de60 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1de70 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1de80 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1de90 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1dea0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1deb0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1dec0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1ded0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1dee0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1def0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1df00 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1df10 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
1df20 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1df30 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1df40 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1df50 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1df60 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1df70 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
1df80 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1df90 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
1dfa0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
1dfb0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
1dfc0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1dfd0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
1dfe0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1dff0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
1e000 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
1e010 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
1e020 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1e030 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
1e040 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
1e050 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
1e060 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
1e070 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
1e080 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1e090 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1e0a0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
1e0b0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1e0c0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
1e0d0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1e0e0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
1e0f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e100 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
1e110 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1e120 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1e130 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1e140 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1e150 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1e160 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
1e170 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1e180 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
1e190 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
1e1a0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1e1b0 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
1e1c0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
1e1d0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1e1e0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1e1f0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1e200 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1e210 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1e220 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1e230 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1e240 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  ck X..**.** ^Onl
1e250 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
1e260 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
1e270 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
1e280 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
1e290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e2a0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
1e2b0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
1e2c0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
1e2d0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
1e2e0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
1e2f0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
1e300 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
1e310 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
1e320 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1e330 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
1e340 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
1e350 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
1e360 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
1e370 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
1e380 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1e390 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1e3a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
1e3b0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
1e3c0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
1e3d0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
1e3e0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
1e3f0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
1e400 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
1e410 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
1e420 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1e430 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1e440 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1e450 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1e460 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1e470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1e480 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1e490 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1e4a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1e4b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e4c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e4d0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1e4e0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1e4f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e500 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1e510 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1e520 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1e530 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ..**.*/.SQLITE_A
1e540 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1e550 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1e560 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1e570 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1e580 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1e590 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1e5a0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1e5b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1e5c0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1e5d0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1e5e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1e5f0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1e600 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1e610 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1e620 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1e630 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1e640 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1e650 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1e660 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e670 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1e680 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1e690 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1e6a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1e6b0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1e6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1e6d0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1e6e0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1e6f0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1e700 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1e710 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1e720 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1e730 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1e740 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1e750 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1e760 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1e770 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1e780 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1e790 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1e7a0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1e7b0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1e7c0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1e7d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1e7e0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1e7f0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1e800 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1e810 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1e820 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1e830 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1e840 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1e850 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1e860 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1e870 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1e880 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1e890 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1e8a0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1e8b0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1e8c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1e8d0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1e8e0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1e8f0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1e900 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1e910 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1e920 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1e930 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1e940 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1e950 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1e960 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1e970 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1e980 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1e990 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1e9a0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1e9b0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1e9c0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1e9d0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1e9e0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1e9f0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1ea00 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1ea10 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1ea20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ea30 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1ea40 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1ea50 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1ea60 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1ea70 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1ea80 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1ea90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1eaa0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1eab0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1eac0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1ead0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1eae0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1eaf0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1eb00 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1eb10 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1eb20 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1eb30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1eb40 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1eb50 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1eb60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1eb70 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1eb80 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1eb90 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1eba0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1ebb0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1ebc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1ebd0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1ebe0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1ebf0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1ec00 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
1ec10 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1ec20 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
1ec30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1ec40 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
1ec50 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1ec60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1ec70 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1ec80 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1ec90 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1eca0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1ecb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1ecc0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1ecd0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1ece0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1ecf0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1ed00 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1ed10 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1ed20 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1ed30 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1ed40 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1ed50 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1ed60 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1ed70 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1ed80 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1ed90 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1eda0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1edb0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1edc0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1edd0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1ede0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1edf0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1ee00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1ee10 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1ee20 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1ee30 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1ee40 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1ee50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1ee60 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1ee70 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1ee80 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
1ee90 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1eea0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1eeb0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1eec0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1eed0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1eee0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1eef0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1ef00 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1ef10 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1ef20 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1ef30 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1ef40 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1ef50 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1ef60 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1ef70 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
1ef80 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
1ef90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1efa0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
1efb0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
1efc0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1efd0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1efe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1eff0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1f000 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1f010 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1f020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f030 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1f040 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1f050 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1f060 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1f070 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1f080 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1f090 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1f0a0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1f0b0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1f0c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1f0d0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1f0e0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1f0f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f100 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1f110 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1f120 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1f130 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1f140 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1f150 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1f160 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1f170 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1f180 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1f190 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1f1a0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1f1b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f1c0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1f1d0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1f1e0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1f1f0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1f200 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1f210 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1f220 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1f230 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1f240 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1f250 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1f260 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1f270 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1f280 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f290 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1f2a0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1f2b0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1f2c0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1f2d0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1f2e0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1f2f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f300 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1f310 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1f320 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1f330 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1f340 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1f350 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1f360 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1f370 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1f380 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1f390 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1f3a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1f3b0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1f3c0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1f3d0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1f3e0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1f3f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1f400 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1f410 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1f420 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1f430 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1f440 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1f450 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1f460 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
1f470 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1f480 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
1f490 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1f4a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1f4b0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
1f4c0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1f4d0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
1f4e0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
1f4f0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
1f500 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
1f510 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
1f520 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
1f530 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1f540 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
1f550 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
1f560 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
1f570 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
1f580 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
1f590 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
1f5a0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
1f5b0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
1f5c0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
1f5d0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
1f5e0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1f5f0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
1f600 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1f610 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
1f620 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
1f630 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
1f640 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
1f650 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1f660 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1f670 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1f680 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1f690 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1f6a0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1f6b0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
1f6c0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
1f6d0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
1f6e0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
1f6f0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
1f700 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
1f710 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
1f720 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
1f730 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
1f740 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
1f750 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
1f760 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
1f770 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
1f780 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
1f790 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
1f7a0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
1f7b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1f7c0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
1f7d0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
1f7e0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1f7f0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
1f800 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
1f810 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
1f820 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
1f830 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
1f840 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
1f850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
1f860 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
1f870 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
1f880 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
1f890 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
1f8a0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
1f8b0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
1f8c0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1f8d0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
1f8e0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
1f8f0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
1f900 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1f910 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
1f920 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
1f930 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
1f940 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
1f950 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
1f960 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
1f970 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1f980 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
1f990 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
1f9a0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
1f9b0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
1f9c0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
1f9d0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
1f9e0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
1f9f0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
1fa00 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
1fa10 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
1fa20 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
1fa30 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
1fa40 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
1fa50 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
1fa60 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
1fa70 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
1fa80 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
1fa90 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
1faa0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
1fab0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
1fac0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
1fad0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
1fae0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
1faf0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
1fb00 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
1fb10 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
1fb20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
1fb30 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
1fb40 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
1fb50 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
1fb60 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
1fb70 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
1fb80 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
1fb90 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
1fba0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
1fbb0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
1fbc0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
1fbd0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
1fbe0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
1fbf0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
1fc00 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
1fc10 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
1fc20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
1fc30 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
1fc40 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
1fc50 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
1fc60 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
1fc70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
1fc80 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
1fc90 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
1fca0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
1fcb0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
1fcc0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
1fcd0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
1fce0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
1fcf0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
1fd00 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
1fd10 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
1fd20 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
1fd30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
1fd40 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
1fd50 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
1fd60 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
1fd70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
1fd80 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1fd90 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
1fda0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
1fdb0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
1fdc0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
1fdd0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
1fde0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
1fdf0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
1fe00 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1fe10 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
1fe20 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
1fe30 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1fe40 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
1fe50 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
1fe60 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
1fe70 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
1fe80 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
1fe90 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
1fea0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
1feb0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
1fec0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
1fed0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
1fee0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1fef0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
1ff00 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
1ff10 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
1ff20 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
1ff30 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
1ff40 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
1ff50 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
1ff60 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
1ff70 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1ff80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1ff90 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1ffa0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
1ffb0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
1ffc0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1ffd0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
1ffe0 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
1fff0 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
20000 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
20010 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
20020 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
20030 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
20040 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
20050 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
20060 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
20070 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20080 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
20090 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
200a0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
200b0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
200c0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
200d0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
200e0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
200f0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
20100 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
20110 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
20120 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
20130 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
20140 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20150 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
20160 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
20170 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
20180 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
20190 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
201a0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
201b0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
201c0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
201d0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
201e0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
201f0 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
20200 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
20210 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
20220 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
20230 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
20240 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
20250 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
20260 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
20270 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
20280 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
20290 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
202a0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
202b0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
202c0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
202d0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
202e0 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
202f0 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
20300 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
20310 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
20320 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
20330 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
20340 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
20350 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20360 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
20370 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
20380 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
20390 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
203a0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
203b0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
203c0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
203d0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
203e0 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
203f0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
20400 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
20410 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
20420 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
20430 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
20440 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
20450 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
20460 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
20470 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
20480 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
20490 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
204a0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
204b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
204c0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
204d0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
204e0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
204f0 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
20500 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
20510 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
20520 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
20530 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
20540 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
20550 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  ur requested by 
20560 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
20570 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
20580 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
20590 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
205a0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
205b0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
205c0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
205d0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
205e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
205f0 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
20600 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
20610 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20620 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
20630 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
20640 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
20650 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
20660 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
20670 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
20680 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
20690 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
206a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
206b0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
206c0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
206d0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
206e0 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
206f0 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
20700 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
20710 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
20720 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
20730 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
20740 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
20750 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
20760 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
20770 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
20780 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
20790 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
207a0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
207b0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
207c0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
207d0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
207e0 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
207f0 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
20800 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
20810 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
20820 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
20830 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
20840 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
20850 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
20860 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
20870 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
20880 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
20890 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
208a0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
208b0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
208c0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
208d0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
208e0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
208f0 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
20900 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
20910 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
20920 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
20930 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
20940 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
20950 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
20960 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
20970 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
20980 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
20990 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
209a0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
209b0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
209c0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
209d0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
209e0 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
209f0 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
20a00 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
20a10 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
20a20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
20a30 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
20a40 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
20a50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
20a60 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
20a70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
20a80 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
20a90 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
20aa0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
20ab0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
20ac0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
20ad0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
20ae0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
20af0 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
20b00 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
20b10 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
20b20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
20b30 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
20b40 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
20b50 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20b60 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
20b70 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
20b80 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
20b90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
20ba0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
20bb0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
20bc0 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
20bd0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
20be0 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
20bf0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20c00 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
20c10 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
20c20 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
20c30 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
20c40 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
20c50 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
20c60 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20c70 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
20c80 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
20c90 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
20ca0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
20cb0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
20cc0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
20cd0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
20ce0 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
20cf0 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
20d00 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
20d10 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
20d20 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
20d30 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
20d40 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
20d50 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
20d60 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
20d70 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
20d80 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
20d90 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
20da0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
20db0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
20dc0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
20dd0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
20de0 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
20df0 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
20e00 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
20e10 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
20e20 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
20e30 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
20e40 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
20e50 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
20e60 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
20e70 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
20e80 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
20e90 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
20ea0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
20eb0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20ec0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
20ed0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
20ee0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
20ef0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
20f00 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
20f10 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
20f20 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
20f30 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
20f40 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
20f50 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
20f60 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
20f70 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
20f80 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
20f90 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
20fa0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
20fb0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
20fc0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
20fd0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
20fe0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
20ff0 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
21000 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
21010 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
21020 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21030 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
21040 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
21050 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
21060 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
21070 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
21080 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
21090 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
210a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
210b0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
210c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
210d0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
210e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
210f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
21100 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21110 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
21120 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
21130 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
21140 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
21150 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
21160 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
21170 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
21180 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
21190 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
211a0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
211b0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
211c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
211d0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
211e0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
211f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
21200 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
21210 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
21220 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
21230 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
21240 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
21250 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
21260 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
21270 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
21280 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
21290 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
212a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
212b0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
212c0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
212d0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
212e0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
212f0 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
21300 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
21310 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
21320 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
21330 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
21340 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
21350 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
21360 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
21370 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
21380 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
21390 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
213a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
213b0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
213c0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
213d0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
213e0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
213f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
21400 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
21410 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
21420 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
21430 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
21440 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
21450 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
21460 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
21470 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
21480 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
21490 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
214a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
214b0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
214c0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
214d0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
214e0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
214f0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
21500 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
21510 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
21520 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
21530 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
21540 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
21550 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
21560 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
21570 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
21580 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
21590 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
215a0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
215b0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
215c0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
215d0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
215e0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
215f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
21600 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
21610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
21620 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
21630 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
21640 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
21650 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
21660 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
21670 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
21680 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
21690 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
216a0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
216b0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
216c0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
216d0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
216e0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
216f0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
21700 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
21710 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
21720 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
21730 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
21740 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
21750 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
21760 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
21770 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
21780 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
21790 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
217a0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
217b0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
217c0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
217d0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
217e0 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
217f0 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
21800 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
21810 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
21820 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
21830 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
21840 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
21850 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
21860 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
21870 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
21880 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
21890 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
218a0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
218b0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
218c0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
218d0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
218e0 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
218f0 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
21900 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
21910 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
21920 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
21930 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
21940 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
21950 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
21960 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
21970 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
21980 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
21990 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
219a0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
219b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
219c0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
219d0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
219e0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
219f0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
21a00 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
21a10 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
21a20 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
21a30 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
21a40 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
21a50 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
21a60 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
21a70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
21a80 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
21a90 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
21aa0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
21ab0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
21ac0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
21ad0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
21ae0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
21af0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
21b00 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
21b10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
21b20 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
21b30 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49  r *zParam);.SQLI
21b40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
21b50 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
21b60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
21b70 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
21b80 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
21b90 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
21ba0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
21bb0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
21bc0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
21bd0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
21be0 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
21bf0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
21c00 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
21c10 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
21c20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
21c30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
21c40 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
21c50 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
21c60 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
21c70 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
21c80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
21c90 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
21ca0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
21cb0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
21cc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21cd0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
21ce0 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
21cf0 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
21d00 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
21d10 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
21d20 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
21d30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
21d40 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
21d50 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
21d60 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
21d70 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
21d80 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
21d90 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
21da0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
21db0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
21dc0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
21dd0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
21de0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
21df0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
21e00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
21e10 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
21e20 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
21e30 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
21e40 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
21e50 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
21e60 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
21e70 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
21e80 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
21e90 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
21ea0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
21eb0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
21ec0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
21ed0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
21ee0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
21ef0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
21f00 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
21f10 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
21f20 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
21f30 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
21f40 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
21f50 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
21f60 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
21f70 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
21f80 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
21f90 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
21fa0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
21fb0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
21fc0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
21fd0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
21fe0 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
21ff0 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
22000 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
22010 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
22020 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
22030 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
22040 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
22050 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
22060 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
22070 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
22080 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
22090 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
220a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
220b0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
220c0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
220d0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
220e0 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
220f0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
22100 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
22110 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
22120 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
22130 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
22140 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
22150 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
22160 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
22170 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
22180 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
22190 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
221a0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
221b0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
221c0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
221d0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
221e0 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
221f0 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
22200 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
22210 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
22220 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
22230 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
22240 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
22250 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
22260 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
22270 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
22280 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
22290 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
222a0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
222b0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
222c0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
222d0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
222e0 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
222f0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
22300 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
22310 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
22320 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
22330 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
22340 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
22350 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
22360 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
22370 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
22380 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
22390 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
223a0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
223b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
223c0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
223d0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
223e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
223f0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
22400 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
22410 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
22420 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
22430 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
22440 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
22450 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
22460 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
22470 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
22480 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22490 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
224a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
224b0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
224c0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
224d0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
224e0 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
224f0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
22500 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
22510 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
22520 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
22530 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
22540 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
22550 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
22560 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
22570 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
22580 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
22590 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
225a0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
225b0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
225c0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
225d0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
225e0 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
225f0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
22600 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
22610 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
22620 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
22630 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
22640 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
22650 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
22660 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
22670 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
22680 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
22690 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
226a0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
226b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
226c0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
226d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
226e0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
226f0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
22700 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
22710 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22720 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
22730 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
22740 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
22750 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
22760 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
22770 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
22780 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22790 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
227a0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
227b0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
227c0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
227d0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
227e0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
227f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22800 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
22810 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
22820 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
22830 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
22840 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
22850 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
22860 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
22870 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
22880 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
22890 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
228a0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
228b0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
228c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
228d0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
228e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
228f0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
22900 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
22910 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
22920 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
22930 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
22940 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
22950 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
22960 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
22970 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
22980 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
22990 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
229a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
229b0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
229c0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
229d0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
229e0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
229f0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
22a00 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
22a10 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
22a20 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
22a30 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
22a40 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
22a50 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
22a60 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
22a70 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
22a80 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
22a90 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
22aa0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
22ab0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
22ac0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
22ad0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
22ae0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
22af0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
22b00 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
22b10 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
22b20 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
22b30 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
22b40 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
22b50 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
22b60 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
22b70 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
22b80 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
22b90 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
22ba0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
22bb0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
22bc0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
22bd0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
22be0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
22bf0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
22c00 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
22c10 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
22c20 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
22c30 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
22c40 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
22c50 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
22c60 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
22c70 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
22c80 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
22c90 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
22ca0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
22cb0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
22cc0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
22cd0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
22ce0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
22cf0 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
22d00 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
22d10 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
22d20 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
22d30 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
22d40 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
22d50 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
22d60 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
22d70 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
22d80 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
22d90 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
22da0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
22db0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
22dc0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
22dd0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
22de0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
22df0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
22e00 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
22e10 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
22e20 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
22e30 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
22e40 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
22e50 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
22e60 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
22e70 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
22e80 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
22e90 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
22ea0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
22eb0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
22ec0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
22ed0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
22ee0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
22ef0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
22f00 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
22f10 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
22f20 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
22f30 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
22f40 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
22f50 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
22f60 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
22f70 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
22f80 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
22f90 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
22fa0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
22fb0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
22fc0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
22fd0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
22fe0 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
22ff0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23000 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
23010 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
23020 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
23030 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
23040 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
23050 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
23060 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
23070 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
23080 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
23090 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
230a0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
230b0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
230c0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
230d0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
230e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
230f0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
23100 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
23110 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
23120 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
23130 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
23140 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
23150 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
23160 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
23170 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
23180 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
23190 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
231a0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
231b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
231c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
231d0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
231e0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
231f0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
23200 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
23210 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23220 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
23230 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
23240 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
23250 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
23260 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
23270 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
23280 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
23290 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
232a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
232b0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
232c0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
232d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
232e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
232f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
23300 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
23310 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
23320 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
23330 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
23340 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23350 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
23360 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
23370 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
23380 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
23390 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
233a0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
233b0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
233c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
233d0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
233e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
233f0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
23400 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
23410 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
23420 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23430 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
23440 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
23450 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
23460 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
23470 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23480 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
23490 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
234a0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
234b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
234c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
234d0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
234e0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
234f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23500 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
23510 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
23520 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
23530 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
23540 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23550 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
23560 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
23570 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
23580 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
23590 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
235a0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
235b0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
235c0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
235d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
235e0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
235f0 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
23600 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
23610 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
23620 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23630 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
23640 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
23650 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
23660 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23670 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
23680 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
23690 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
236a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
236b0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
236c0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
236d0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
236e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
236f0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
23700 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
23710 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23720 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
23730 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
23740 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
23750 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
23760 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
23770 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
23780 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
23790 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
237a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
237b0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
237c0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
237d0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
237e0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
237f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
23800 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
23810 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
23820 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
23830 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
23840 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
23850 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
23860 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
23870 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
23880 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23890 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
238a0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
238b0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
238c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
238d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
238e0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
238f0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
23900 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
23910 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
23920 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
23930 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
23940 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
23950 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
23960 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
23970 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
23980 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
23990 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
239a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
239b0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
239c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
239d0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
239e0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
239f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23a00 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
23a10 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
23a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23a30 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
23a40 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
23a50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23a60 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
23a70 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
23a80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23a90 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23aa0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
23ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23ac0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
23ad0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
23ae0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23af0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
23b00 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
23b10 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
23b20 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
23b30 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
23b40 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
23b50 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
23b60 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
23b70 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
23b80 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
23b90 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
23ba0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
23bb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
23bc0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
23bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23be0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
23bf0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
23c00 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
23c10 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
23c20 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23c30 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
23c40 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
23c50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23c60 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
23c70 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
23c80 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23c90 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
23ca0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
23cb0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
23cc0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
23cd0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
23ce0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
23cf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
23d00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
23d10 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
23d20 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
23d30 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
23d40 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
23d50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23d60 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
23d70 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
23d80 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
23d90 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
23da0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
23db0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
23dc0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
23dd0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
23de0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
23df0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
23e00 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
23e10 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
23e20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
23e30 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
23e40 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
23e50 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
23e60 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
23e70 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
23e80 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
23e90 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
23ea0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
23eb0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
23ec0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
23ed0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
23ee0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
23ef0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
23f00 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
23f10 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
23f20 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
23f30 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
23f40 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
23f50 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
23f60 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
23f70 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
23f80 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23f90 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
23fa0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
23fb0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
23fc0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
23fd0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
23fe0 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
23ff0 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
24000 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
24010 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
24020 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
24030 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
24040 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
24050 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
24060 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
24070 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
24080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
24090 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
240a0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
240b0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
240c0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
240d0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
240e0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
240f0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
24100 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
24110 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
24120 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
24130 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
24140 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24150 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
24160 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
24170 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24180 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
24190 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
241a0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
241b0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
241c0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
241d0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
241e0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
241f0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
24200 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
24210 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
24220 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
24230 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
24240 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
24250 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
24260 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
24270 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
24280 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24290 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
242a0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
242b0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
242c0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
242d0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
242e0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
242f0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
24300 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
24310 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
24320 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
24330 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
24340 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
24350 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
24360 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
24370 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24380 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
24390 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
243a0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
243b0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
243c0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
243d0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
243e0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
243f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
24400 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
24410 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
24420 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
24430 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
24440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
24450 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
24460 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
24470 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
24480 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
24490 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
244a0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
244b0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
244c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
244d0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
244e0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
244f0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
24500 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
24510 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
24520 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
24530 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
24540 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
24550 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
24560 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
24570 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
24580 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
24590 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
245a0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
245b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
245c0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
245d0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
245e0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
245f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
24600 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24610 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
24620 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
24630 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
24640 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
24650 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
24660 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
24670 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
24680 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24690 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
246a0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
246b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
246c0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
246d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
246e0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
246f0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
24700 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
24710 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
24720 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
24730 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
24740 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
24750 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
24760 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
24770 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
24780 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
24790 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
247a0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
247b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
247c0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
247d0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
247e0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
247f0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
24800 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
24810 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
24820 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
24830 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
24840 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
24850 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
24860 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
24870 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
24880 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
24890 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
248a0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
248b0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
248c0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
248d0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
248e0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
248f0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
24900 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
24910 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
24920 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
24930 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
24940 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
24950 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
24960 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
24970 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
24980 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
24990 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
249a0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
249b0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
249c0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
249d0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
249e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
249f0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
24a00 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
24a10 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
24a20 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
24a30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
24a40 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
24a50 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
24a60 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
24a70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24a80 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
24a90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
24aa0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
24ab0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
24ac0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
24ad0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
24ae0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
24af0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
24b00 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
24b10 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
24b20 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
24b30 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
24b40 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
24b50 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
24b60 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
24b70 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
24b80 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
24b90 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
24ba0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
24bb0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
24bc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24bd0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
24be0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
24bf0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
24c00 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
24c10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
24c20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
24c30 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
24c40 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
24c50 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
24c60 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24c70 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24c80 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
24c90 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
24ca0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
24cb0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24cc0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
24cd0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24ce0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24cf0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24d00 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
24d10 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24d20 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
24d30 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
24d40 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
24d50 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
24d60 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
24d70 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
24d80 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
24d90 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
24da0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
24db0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
24dc0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
24dd0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
24de0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
24df0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
24e00 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
24e10 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
24e20 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
24e30 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
24e40 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
24e50 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
24e60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24e70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
24e80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
24e90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
24ea0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
24eb0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
24ec0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
24ed0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
24ee0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
24ef0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
24f00 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
24f10 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
24f20 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
24f30 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
24f40 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
24f50 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
24f60 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
24f70 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
24f80 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
24f90 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
24fa0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
24fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24fc0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
24fd0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
24fe0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
24ff0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
25000 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
25010 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
25020 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
25030 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
25040 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25050 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
25060 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
25070 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
25080 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
25090 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
250a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
250b0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
250c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
250d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
250e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
250f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
25100 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
25110 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
25120 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
25130 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
25140 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
25150 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
25160 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
25170 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
25180 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
25190 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
251a0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
251b0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
251c0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
251d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
251e0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
251f0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
25200 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25210 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
25220 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
25230 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
25240 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
25250 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
25260 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
25270 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
25280 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
25290 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
252a0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
252b0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
252c0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
252d0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
252e0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
252f0 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
25300 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
25310 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
25320 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
25330 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
25340 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
25350 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
25360 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
25370 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
25380 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
25390 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
253a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
253b0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
253c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
253d0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
253e0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
253f0 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
25400 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
25410 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
25420 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
25430 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
25440 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
25450 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
25460 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
25470 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
25480 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
25490 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
254a0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
254b0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
254c0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
254d0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
254e0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
254f0 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
25500 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
25510 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
25520 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
25530 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
25540 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
25550 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
25560 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
25570 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
25580 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
25590 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
255a0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
255b0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
255c0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
255d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
255e0 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
255f0 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
25600 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
25610 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
25620 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
25630 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
25640 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
25650 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
25660 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
25670 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
25680 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25690 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
256a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
256b0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
256c0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
256d0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
256e0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
256f0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
25700 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
25710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25720 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
25730 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
25740 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
25750 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25760 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
25770 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
25780 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
25790 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
257a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
257b0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
257c0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
257d0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
257e0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
257f0 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
25800 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
25810 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
25820 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
25830 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
25840 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
25850 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
25860 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
25870 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
25880 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
25890 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
258a0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
258b0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
258c0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
258d0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
258e0 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
258f0 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
25900 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
25910 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
25920 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
25930 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
25940 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
25950 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
25960 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
25970 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
25980 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
25990 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
259a0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
259b0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
259c0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
259d0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  ion open..*/.SQL
259e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
259f0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
25a00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
25a10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25a20 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
25a30 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
25a40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
25a50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25a60 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
25a70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
25a80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
25a90 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
25aa0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
25ab0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
25ac0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
25ad0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
25ae0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
25af0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
25b00 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
25b10 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
25b20 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
25b30 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
25b40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
25b50 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
25b60 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
25b70 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
25b80 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
25b90 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
25ba0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25bb0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
25bc0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
25bd0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
25be0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
25bf0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
25c00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25c10 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
25c20 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
25c30 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
25c40 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
25c50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25c60 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
25c70 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
25c80 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
25c90 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
25ca0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
25cb0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
25cc0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
25cd0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25ce0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
25cf0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
25d00 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
25d10 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
25d20 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
25d30 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
25d40 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
25d50 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
25d60 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25d70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25d80 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
25d90 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
25da0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25db0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25dc0 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
25dd0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
25de0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
25df0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
25e00 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
25e10 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
25e20 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
25e30 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
25e40 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
25e50 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
25e60 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
25e70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
25e80 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
25e90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
25ea0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
25eb0 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
25ec0 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
25ed0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
25ee0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
25ef0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
25f00 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
25f10 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
25f20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
25f30 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
25f40 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
25f50 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
25f60 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
25f70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
25f80 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
25f90 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
25fa0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
25fb0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
25fc0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
25fd0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
25fe0 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
25ff0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
26000 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
26010 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
26020 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
26030 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
26040 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
26050 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
26060 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
26070 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
26080 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
26090 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
260a0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
260b0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
260c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
260d0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
260e0 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
260f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26100 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
26110 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
26120 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
26130 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
26140 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
26150 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
26160 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
26170 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
26180 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
26190 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
261a0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
261b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
261c0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
261d0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
261e0 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
261f0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
26200 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
26210 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
26220 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
26230 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
26240 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
26250 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
26260 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
26270 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
26280 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
26290 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
262a0 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
262b0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
262c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
262d0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
262e0 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
262f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
26300 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
26310 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
26320 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
26330 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
26340 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
26350 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
26360 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
26370 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
26380 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
26390 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
263a0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
263b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
263c0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
263d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
263e0 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
263f0 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
26400 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
26410 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
26420 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
26430 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
26440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
26450 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
26460 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
26470 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
26480 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
26490 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
264a0 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
264b0 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
264c0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
264d0 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
264e0 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
264f0 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
26500 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
26510 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
26520 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
26530 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
26540 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
26550 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
26560 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
26570 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
26580 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
26590 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
265a0 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
265b0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
265c0 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
265d0 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
265e0 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
265f0 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
26600 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
26610 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
26620 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
26630 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
26640 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
26650 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
26660 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
26670 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
26680 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
26690 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
266a0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
266b0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
266c0 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
266d0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
266e0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
266f0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
26700 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
26710 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
26720 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
26730 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
26740 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
26750 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
26760 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
26770 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
26780 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
26790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
267a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
267b0 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
267c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
267d0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
267e0 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
267f0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
26800 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
26810 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
26820 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
26830 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
26840 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
26850 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
26860 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
26870 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
26880 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
26890 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
268a0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
268b0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
268c0 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
268d0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
268e0 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
268f0 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
26900 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
26910 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
26920 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
26930 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
26940 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
26950 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
26960 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
26970 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
26980 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
26990 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
269a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
269b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
269c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
269d0 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
269e0 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
269f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
26a00 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
26a10 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
26a20 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
26a30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
26a40 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
26a50 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
26a60 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
26a70 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
26a80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
26a90 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
26aa0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
26ab0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
26ac0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
26ad0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
26ae0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
26af0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
26b00 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
26b10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26b20 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
26b30 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
26b40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26b50 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
26b60 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
26b70 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
26b80 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
26b90 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
26ba0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
26bb0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
26bc0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
26bd0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
26be0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
26bf0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
26c00 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
26c10 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
26c20 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
26c30 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
26c40 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
26c50 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
26c60 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
26c70 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26c80 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
26c90 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
26ca0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
26cb0 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
26cc0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
26cd0 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
26ce0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
26cf0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
26d00 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
26d10 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
26d20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
26d30 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
26d40 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
26d50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
26d60 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
26d70 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
26d80 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
26d90 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
26da0 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
26db0 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
26dc0 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
26dd0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
26de0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
26df0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
26e00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
26e10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
26e20 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
26e30 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
26e40 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
26e50 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
26e60 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
26e70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
26e80 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
26e90 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
26ea0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
26eb0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
26ec0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
26ed0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
26ee0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
26ef0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
26f00 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
26f10 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
26f20 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
26f30 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
26f40 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
26f50 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
26f60 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
26f70 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
26f80 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
26f90 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
26fa0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
26fb0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
26fc0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
26fd0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
26fe0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
26ff0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
27000 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
27010 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
27020 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
27030 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
27040 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
27050 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
27060 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
27070 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
27080 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
27090 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
270a0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
270b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
270c0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
270d0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
270e0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
270f0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
27100 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
27110 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
27120 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
27130 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
27140 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
27150 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
27160 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
27170 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
27180 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
27190 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
271a0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
271b0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
271c0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
271d0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
271e0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
271f0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
27200 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
27210 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
27220 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
27230 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
27240 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
27250 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
27260 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
27270 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27280 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
27290 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
272a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
272b0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
272c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
272d0 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
272e0 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
272f0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
27300 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
27310 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
27320 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
27330 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
27340 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
27350 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
27360 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
27370 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
27380 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
27390 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
273a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
273b0 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
273c0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
273d0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
273e0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
273f0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
27400 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
27410 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
27420 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
27430 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
27440 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
27450 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
27460 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
27470 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27480 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
27490 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
274a0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
274b0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
274c0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
274d0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
274e0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
274f0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
27500 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
27510 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
27520 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
27530 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
27540 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
27550 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
27560 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
27570 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
27580 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
27590 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
275a0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
275b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
275c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
275d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
275e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
275f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
27600 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
27610 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
27620 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
27630 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27640 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
27650 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
27660 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
27670 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27680 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
27690 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
276a0 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
276b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
276c0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
276d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
276e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
276f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27700 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
27710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27720 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
27730 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
27740 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
27750 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
27760 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
27770 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
27780 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27790 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
277a0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
277b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
277c0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
277d0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
277e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
277f0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
27800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
27810 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
27820 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
27830 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
27840 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
27850 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
27860 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
27870 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
27880 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
27890 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
278a0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
278b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
278c0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
278d0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
278e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
278f0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
27900 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
27910 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
27920 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
27930 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
27940 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
27950 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
27960 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
27970 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
27980 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
27990 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
279a0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
279b0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
279c0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
279d0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
279e0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
279f0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
27a00 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
27a10 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
27a20 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
27a30 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
27a40 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
27a50 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
27a60 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
27a70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
27a80 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
27a90 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
27aa0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
27ab0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
27ac0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
27ad0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
27ae0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
27af0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27b00 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
27b10 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27b20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27b30 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
27b40 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
27b50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27b60 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
27b70 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
27b80 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
27b90 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
27ba0 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
27bb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
27bc0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
27bd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27be0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
27bf0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
27c00 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
27c10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27c20 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
27c30 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
27c40 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
27c50 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
27c60 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
27c70 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
27c80 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
27c90 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
27ca0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
27cb0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
27cc0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
27cd0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
27ce0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
27cf0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
27d00 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
27d10 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
27d20 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
27d30 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
27d40 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
27d50 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
27d60 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
27d70 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
27d80 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
27d90 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
27da0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
27db0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
27dc0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
27dd0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
27de0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
27df0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
27e00 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
27e10 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
27e20 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
27e30 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
27e40 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
27e50 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
27e60 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
27e70 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
27e80 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
27e90 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
27ea0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
27eb0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
27ec0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
27ed0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
27ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
27ef0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
27f00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27f10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27f20 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27f30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27f40 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27f50 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
27f60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27f70 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
27f80 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27f90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27fa0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
27fb0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
27fc0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
27fd0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
27fe0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
27ff0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
28000 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
28010 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
28020 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
28030 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
28040 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
28050 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
28060 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
28070 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
28080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
28090 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
280a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
280b0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
280c0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
280d0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
280e0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
280f0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
28100 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
28110 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
28120 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
28130 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
28140 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
28150 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
28160 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28170 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
28180 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
28190 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
281a0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
281b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
281c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
281d0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
281e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
281f0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
28200 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28220 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
28230 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
28240 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
28250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28260 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
28270 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
28280 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
28290 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
282a0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
282b0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
282c0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
282d0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
282e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
282f0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
28300 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28310 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
28320 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
28330 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
28340 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
28350 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
28360 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
28370 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
28380 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
28390 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
283a0 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
283b0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
283c0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
283d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
283e0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
283f0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
28400 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
28410 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
28420 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
28430 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
28440 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
28450 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
28460 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
28470 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
28480 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
28490 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
284a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
284b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
284c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
284d0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
284e0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
284f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
28500 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
28510 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
28520 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
28530 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
28540 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
28550 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
28560 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
28570 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
28580 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
28590 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
285a0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
285b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
285c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
285d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
285e0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
285f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
28600 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
28610 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
28620 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
28630 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
28640 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
28650 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28660 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28670 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
28680 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
28690 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
286a0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
286b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
286c0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
286d0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
286e0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
286f0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
28700 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
28710 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
28720 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
28730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28740 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
28750 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
28760 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
28770 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
28780 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
28790 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
287a0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
287b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
287c0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
287d0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
287e0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
287f0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
28800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
28810 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
28820 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
28830 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
28840 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
28850 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
28860 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
28870 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
28880 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
28890 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
288a0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
288b0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
288c0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
288d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
288e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
288f0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
28900 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
28910 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28920 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
28930 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
28940 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
28950 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
28960 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
28970 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
28980 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
28990 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
289a0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
289b0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
289c0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
289d0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
289e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
289f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28a00 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
28a10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
28a20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
28a30 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28a40 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
28a50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28a60 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
28a70 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
28a80 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
28a90 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
28aa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
28ab0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
28ac0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
28ad0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
28ae0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
28af0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
28b00 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
28b10 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
28b20 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
28b30 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
28b40 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
28b50 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
28b60 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
28b70 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
28b80 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
28b90 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
28ba0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
28bb0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
28bc0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
28bd0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
28be0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
28bf0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
28c00 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
28c10 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
28c20 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
28c30 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
28c40 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
28c50 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
28c60 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
28c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
28c80 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
28c90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
28ca0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
28cb0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
28cc0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
28cd0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
28ce0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
28cf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
28d00 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
28d10 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
28d20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
28d30 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
28d40 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
28d50 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
28d60 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
28d70 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
28d80 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
28d90 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
28da0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
28db0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
28dc0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
28dd0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
28de0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
28df0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
28e00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28e10 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
28e20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
28e30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
28e40 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
28e50 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
28e60 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
28e70 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
28e80 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
28e90 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
28ea0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
28eb0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
28ec0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
28ed0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
28ee0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
28ef0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
28f00 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
28f10 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
28f20 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
28f30 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
28f40 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
28f50 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
28f60 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
28f70 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
28f80 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
28f90 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
28fa0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
28fb0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
28fc0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
28fd0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
28fe0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
28ff0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
29000 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
29010 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
29020 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
29030 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
29040 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
29050 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
29060 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
29070 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
29080 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
29090 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
290a0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
290b0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
290c0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
290d0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
290e0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
290f0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
29100 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
29110 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
29120 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
29130 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
29140 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
29150 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
29160 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
29170 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
29180 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
29190 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
291a0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
291b0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
291c0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
291d0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
291e0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
291f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
29200 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
29210 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
29220 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
29230 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
29240 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
29250 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
29260 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
29270 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
29280 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
29290 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
292a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
292b0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
292c0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
292d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
292e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
292f0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
29300 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29310 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
29320 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
29330 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
29340 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
29350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
29360 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
29370 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29380 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
29390 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
293a0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
293b0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
293c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
293d0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
293e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
293f0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
29400 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
29410 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
29420 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
29430 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
29440 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
29460 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
29470 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
29480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
29490 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
294a0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
294b0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
294c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
294d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
294e0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
294f0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
29500 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
29510 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
29520 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
29530 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
29540 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
29550 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
29560 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
29570 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
29580 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
29590 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
295a0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
295b0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
295c0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
295d0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
295e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
295f0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
29600 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
29610 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
29620 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
29630 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
29640 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
29650 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
29660 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
29670 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
29680 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
29690 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
296a0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
296b0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
296c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
296d0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
296e0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
296f0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
29700 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
29710 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
29720 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
29730 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
29740 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
29750 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
29760 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
29770 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
29780 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
29790 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
297a0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
297b0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
297c0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
297d0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
297e0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
297f0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
29800 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
29810 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
29820 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
29830 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
29840 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
29850 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
29860 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
29870 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
29880 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
29890 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
298a0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
298b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
298c0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
298d0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
298e0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
298f0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
29900 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
29910 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
29920 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
29930 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
29940 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
29950 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29960 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29970 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
29980 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
29990 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
299a0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
299b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
299c0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
299d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
299e0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
299f0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
29a00 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
29a10 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
29a20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29a30 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
29a40 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
29a50 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
29a60 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
29a70 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29a80 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
29a90 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
29aa0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
29ab0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
29ac0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
29ad0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
29ae0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
29af0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
29b00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
29b10 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
29b20 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
29b30 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
29b40 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
29b50 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
29b60 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
29b70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29b80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
29b90 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
29ba0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
29bb0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
29bc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
29bd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
29be0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
29bf0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
29c00 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
29c10 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
29c20 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
29c30 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
29c40 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
29c50 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
29c60 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
29c70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
29c80 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
29c90 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
29ca0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
29cb0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
29cc0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
29cd0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
29ce0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
29cf0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
29d00 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
29d10 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
29d20 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
29d30 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
29d40 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
29d50 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
29d60 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
29d70 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
29d80 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
29d90 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
29da0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
29db0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
29dc0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
29dd0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
29de0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
29df0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
29e00 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
29e10 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
29e20 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
29e30 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
29e40 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
29e50 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
29e60 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
29e70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29e80 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
29e90 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
29ea0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
29eb0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
29ec0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
29ed0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
29ee0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
29ef0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
29f00 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
29f10 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
29f20 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
29f30 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
29f40 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
29f50 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
29f60 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
29f70 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
29f80 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
29f90 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
29fa0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
29fb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
29fc0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
29fd0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
29fe0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
29ff0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2a000 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2a010 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2a020 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2a030 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2a040 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2a050 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2a060 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2a070 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2a080 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2a090 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2a0a0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2a0b0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2a0c0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2a0d0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2a0e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2a0f0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2a100 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2a110 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2a120 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2a130 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2a140 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2a150 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2a160 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2a170 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2a180 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2a190 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2a1a0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2a1b0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2a1c0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2a1d0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2a1e0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2a1f0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2a200 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2a210 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2a220 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2a230 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2a240 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2a250 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2a260 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2a270 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2a280 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2a290 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2a2a0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2a2b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2a2c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2a2d0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2a2e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a2f0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2a300 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2a310 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2a320 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2a330 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2a340 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2a350 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2a360 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2a370 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2a380 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2a390 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2a3a0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2a3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2a3c0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2a3d0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2a3e0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2a3f0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2a400 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2a410 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2a420 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2a430 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2a440 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2a450 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2a460 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2a470 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2a480 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2a490 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2a4a0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2a4b0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2a4c0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2a4d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2a4e0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2a4f0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2a500 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2a510 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a520 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2a530 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2a540 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2a550 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2a560 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2a570 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2a580 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2a590 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2a5a0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2a5b0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2a5c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a5d0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2a5e0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2a5f0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2a600 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2a610 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2a620 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2a630 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2a640 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2a650 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2a660 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2a670 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2a680 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2a690 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2a6a0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2a6b0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2a6c0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2a6d0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2a6e0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2a6f0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2a700 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2a710 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2a720 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2a730 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2a740 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2a750 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2a760 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2a770 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2a780 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2a790 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2a7a0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2a7b0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2a7c0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2a7d0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2a7e0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2a7f0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2a800 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2a810 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2a820 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2a830 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2a840 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2a850 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2a860 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2a870 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2a880 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2a890 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2a8a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2a8b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a8c0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2a8d0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2a8e0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2a8f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2a900 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2a910 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2a920 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2a930 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2a940 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2a950 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2a960 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2a970 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2a980 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2a990 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2a9a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2a9b0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2a9c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a9d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2a9e0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2a9f0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2aa00 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2aa10 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2aa20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2aa30 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2aa40 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2aa50 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2aa60 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2aa70 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2aa80 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2aa90 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2aaa0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2aab0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2aac0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2aad0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2aae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2aaf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ab00 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2ab10 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2ab20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2ab30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ab40 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2ab50 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2ab60 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2ab70 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2ab80 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2ab90 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2aba0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2abb0 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2abc0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2abd0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2abe0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2abf0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2ac00 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2ac10 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2ac20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2ac30 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2ac40 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2ac50 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2ac60 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2ac70 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2ac80 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2ac90 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2aca0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2acb0 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2acc0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2acd0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2ace0 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2acf0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2ad00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2ad10 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2ad20 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2ad30 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2ad40 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2ad50 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2ad60 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2ad70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ad80 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2ad90 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2ada0 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2adb0 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2adc0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2add0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2ade0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2adf0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2ae00 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2ae10 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2ae20 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2ae30 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2ae40 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2ae50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2ae60 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2ae70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2ae80 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2ae90 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2aea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2aeb0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2aec0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2aed0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2aee0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2aef0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2af00 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2af10 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2af20 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2af30 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2af40 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2af50 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2af60 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2af70 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2af80 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2af90 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2afa0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2afb0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2afc0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2afd0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2afe0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2aff0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2b000 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2b010 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2b020 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2b030 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2b040 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2b050 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2b060 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2b070 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2b080 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2b090 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2b0a0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2b0b0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2b0c0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2b0d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b0e0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2b0f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2b100 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2b110 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2b120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b130 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2b140 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2b150 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2b160 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2b170 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2b180 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2b190 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2b1a0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2b1b0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2b1c0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2b1d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2b1e0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2b1f0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2b200 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2b210 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
2b220 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
2b230 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2b240 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2b250 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2b260 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2b270 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2b280 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2b290 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2b2a0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2b2b0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2b2c0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2b2d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b2e0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2b2f0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2b300 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2b310 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2b320 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2b330 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b340 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2b350 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2b360 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2b370 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2b380 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2b390 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2b3a0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2b3b0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2b3c0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2b3d0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2b3e0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2b3f0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2b400 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2b410 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2b420 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2b430 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2b440 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2b450 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2b460 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2b470 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2b480 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2b490 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2b4a0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2b4b0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2b4c0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2b4d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2b4e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2b4f0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2b500 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2b510 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2b520 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b530 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2b540 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2b550 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2b560 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2b570 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b580 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2b590 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2b5a0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2b5b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2b5c0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2b5d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b5e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2b5f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2b600 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2b610 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2b620 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2b630 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2b640 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2b650 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2b660 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2b670 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2b680 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b690 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2b6a0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2b6b0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2b6c0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2b6d0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2b6e0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2b6f0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2b700 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2b710 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2b720 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2b730 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2b740 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2b750 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2b760 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2b770 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2b780 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2b790 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2b7a0 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2b7b0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2b7c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2b7d0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2b7e0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2b7f0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2b800 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2b810 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2b820 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2b830 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2b840 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2b850 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2b860 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2b870 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2b880 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2b890 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2b8a0 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2b8b0 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2b8c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2b8d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2b8e0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2b8f0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2b900 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2b910 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2b920 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2b930 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2b940 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2b950 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2b960 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2b970 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2b980 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2b990 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2b9a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2b9b0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2b9c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2b9d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2b9e0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2b9f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2ba00 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2ba10 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2ba20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ba30 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2ba40 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2ba50 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2ba60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ba70 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2ba80 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2ba90 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2baa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bab0 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2bac0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2bad0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2bae0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2baf0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2bb00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2bb10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2bb20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2bb30 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2bb40 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2bb50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bb60 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2bb70 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2bb80 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2bb90 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2bba0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2bbb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bbc0 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2bbd0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2bbe0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2bbf0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2bc00 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2bc10 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2bc20 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2bc30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bc40 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2bc50 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2bc60 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2bc70 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2bc80 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2bc90 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2bca0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2bcb0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2bcc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2bcd0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2bce0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2bcf0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2bd00 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2bd10 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2bd20 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2bd30 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2bd40 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2bd50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2bd60 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2bd70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2bd80 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2bd90 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2bda0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2bdb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2bdc0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2bdd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2bde0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2bdf0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2be00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2be10 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2be20 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2be30 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2be40 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2be50 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2be60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2be70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2be80 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2be90 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2bea0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2beb0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2bec0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2bed0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2bee0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2bef0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2bf00 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2bf10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bf20 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2bf30 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2bf40 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2bf50 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2bf60 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2bf70 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2bf80 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2bf90 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2bfa0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2bfb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
2bfc0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2bfd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2bfe0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2bff0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2c000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c010 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2c020 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c030 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2c040 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2c050 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2c060 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2c070 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c080 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2c090 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2c0a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c0b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2c0c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2c0d0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c0e0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2c0f0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2c100 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2c110 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2c120 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2c130 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2c140 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2c150 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2c160 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2c170 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2c180 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c190 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c1a0 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2c1b0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2c1c0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2c1d0 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
2c1e0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
2c1f0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
2c200 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
2c210 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
2c220 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
2c230 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2c240 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
2c250 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
2c260 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
2c270 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
2c280 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
2c290 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2c2a0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2c2b0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2c2c0 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2c2d0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2c2e0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2c2f0 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2c300 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2c310 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2c320 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2c330 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2c340 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2c350 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2c360 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2c370 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2c380 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2c390 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2c3a0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2c3b0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2c3c0 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2c3d0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2c3e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2c3f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2c400 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2c410 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2c420 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2c430 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2c440 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2c450 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2c460 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2c470 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2c480 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2c490 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2c4a0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2c4b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2c4c0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2c4d0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2c4e0 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2c4f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2c500 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2c510 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2c520 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
2c530 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2c540 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2c550 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2c560 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2c570 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2c580 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2c590 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2c5a0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
2c5b0 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
2c5c0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2c5d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2c5e0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
2c5f0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2c600 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2c610 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
2c620 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2c630 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2c640 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2c650 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2c660 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2c670 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2c680 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2c690 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
2c6a0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2c6b0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2c6c0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2c6d0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2c6e0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2c6f0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2c700 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2c710 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2c720 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2c730 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2c740 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2c750 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2c760 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2c770 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2c780 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2c790 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2c7a0 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2c7b0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2c7c0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2c7d0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2c7e0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2c7f0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2c800 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2c810 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2c820 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2c830 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2c840 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2c850 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2c860 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2c870 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2c880 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2c890 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2c8a0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2c8b0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2c8c0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2c8d0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2c8e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2c8f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c900 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2c910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c920 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2c930 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2c940 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2c950 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2c960 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2c970 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2c980 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2c990 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2c9a0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2c9b0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2c9c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2c9d0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2c9e0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2c9f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2ca00 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2ca10 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2ca20 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2ca30 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2ca40 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2ca50 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2ca60 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2ca70 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2ca80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ca90 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2caa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cab0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2cac0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2cad0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2cae0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2caf0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2cb00 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2cb10 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2cb20 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2cb30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cb40 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2cb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2cb60 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2cb70 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2cb80 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2cb90 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2cba0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2cbb0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2cbc0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2cbd0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2cbe0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2cbf0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2cc00 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2cc10 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2cc20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2cc30 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2cc40 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2cc50 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2cc60 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2cc70 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2cc80 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2cc90 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2cca0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2ccb0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2ccc0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2ccd0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2cce0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2ccf0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2cd00 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2cd10 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2cd20 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2cd30 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2cd40 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2cd50 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2cd60 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2cd70 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2cd80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2cd90 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2cda0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2cdb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2cdc0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2cdd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cde0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2cdf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ce00 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2ce10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ce20 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2ce30 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2ce40 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2ce50 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2ce60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ce70 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2ce80 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2ce90 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2cea0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2ceb0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2cec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2ced0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2cee0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2cef0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2cf00 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2cf10 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2cf20 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2cf30 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2cf40 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2cf50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cf60 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2cf70 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2cf80 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2cf90 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2cfa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cfb0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2cfc0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2cfd0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2cfe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cff0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2d000 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2d010 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2d020 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2d030 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2d040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d050 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2d060 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2d070 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2d080 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2d090 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2d0a0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2d0b0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2d0c0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2d0d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d0e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2d0f0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2d100 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2d110 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2d120 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2d130 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2d140 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2d150 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2d160 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2d170 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2d180 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d190 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2d1a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2d1b0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2d1c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2d1d0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2d1e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2d1f0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2d200 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2d210 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2d220 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2d230 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2d240 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2d250 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2d260 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2d270 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2d280 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2d290 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2d2a0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2d2b0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2d2c0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2d2d0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2d2e0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2d2f0 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51  _NOMEM].)^.*/.SQ
2d300 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2d310 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2d320 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2d330 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d340 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d350 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d360 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2d370 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d380 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d3a0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2d3b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d3c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
2d3d0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2d3e0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2d3f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d400 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d410 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d420 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2d430 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2d440 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
2d450 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2d460 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
2d470 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d480 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2d490 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
2d4a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d4b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2d4c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d4d0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2d4e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2d4f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2d500 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d510 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2d520 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2d530 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2d540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d550 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2d560 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  API sqlite3_valu
2d570 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2d580 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2d590 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d5a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d5b0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2d5c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2d5d0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
2d5e0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2d5f0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
2d600 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
2d610 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2d620 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
2d630 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2d640 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
2d650 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
2d660 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
2d670 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
2d680 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
2d690 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
2d6a0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2d6b0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
2d6c0 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
2d6d0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
2d6e0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2d6f0 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
2d700 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
2d710 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d720 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
2d730 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2d740 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
2d750 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2d760 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2d770 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2d780 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
2d790 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2d7a0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
2d7b0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
2d7c0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2d7d0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
2d7e0 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
2d7f0 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
2d800 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
2d810 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
2d820 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2d830 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
2d840 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
2d850 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
2d860 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2d870 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2d880 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
2d890 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2d8a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
2d8b0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
2d8c0 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
2d8d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
2d8e0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
2d8f0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
2d900 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
2d910 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
2d920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2d930 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
2d940 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
2d950 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
2d960 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
2d970 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d980 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
2d990 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2d9a0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2d9b0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2d9c0 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
2d9d0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d9e0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2d9f0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2da00 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
2da10 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
2da20 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
2da30 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
2da40 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
2da50 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
2da60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2da70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2da80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2da90 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2daa0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2dab0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2dac0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2dad0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2dae0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2daf0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2db00 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2db10 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2db20 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2db30 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2db40 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2db50 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2db60 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2db70 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2db80 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2db90 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2dba0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2dbb0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2dbc0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2dbd0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2dbe0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2dbf0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2dc00 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2dc10 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2dc20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2dc30 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2dc40 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2dc50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dc60 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2dc70 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2dc80 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2dc90 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2dca0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2dcb0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2dcc0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2dcd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dce0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2dcf0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2dd00 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2dd10 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2dd20 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2dd30 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2dd40 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2dd50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2dd60 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2dd70 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2dd80 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2dd90 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2dda0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2ddb0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2ddc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2ddd0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2dde0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2ddf0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2de00 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2de10 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2de20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2de30 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2de40 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2de50 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2de60 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2de70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2de80 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2de90 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2dea0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
2deb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2dec0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2ded0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2dee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2def0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2df00 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2df10 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
2df20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
2df30 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
2df40 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2df50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2df60 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
2df70 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2df80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2df90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
2dfa0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2dfb0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2dfc0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2dfd0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2dfe0 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2dff0 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2e000 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2e010 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2e020 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2e030 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2e040 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2e050 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2e060 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2e070 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
2e080 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
2e090 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
2e0a0 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
2e0b0 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
2e0c0 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
2e0d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
2e0e0 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
2e0f0 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
2e100 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
2e110 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
2e120 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
2e130 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2e140 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2e150 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2e160 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2e170 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2e180 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
2e190 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
2e1a0 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
2e1b0 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
2e1c0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
2e1d0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2e1e0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2e1f0 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
2e200 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2e210 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
2e220 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
2e230 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
2e240 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
2e250 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
2e260 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2e270 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2e280 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2e290 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
2e2a0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
2e2b0 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
2e2c0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
2e2d0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
2e2e0 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
2e2f0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
2e300 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
2e310 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2e320 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
2e330 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
2e340 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
2e350 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
2e360 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
2e370 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
2e380 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
2e390 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
2e3a0 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
2e3b0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
2e3c0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
2e3d0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
2e3e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2e3f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2e400 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
2e410 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2e420 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
2e430 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2e440 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
2e450 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
2e460 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
2e470 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
2e480 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2e490 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
2e4a0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2e4b0 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
2e4c0 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
2e4d0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
2e4e0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2e4f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2e500 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
2e510 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
2e520 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
2e530 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
2e540 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
2e550 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
2e560 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2e570 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2e580 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
2e590 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
2e5a0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
2e5b0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
2e5c0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
2e5d0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
2e5e0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45  s parameters.  E
2e5f0 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f  very SQL functio
2e600 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e610 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f   must be able to
2e620 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54   work.** with UT
2e630 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
2e640 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
2e650 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
2e660 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
2e670 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
2e680 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
2e690 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
2e6a0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
2e6b0 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
2e6c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e6d0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
2e6e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e6f0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
2e700 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
2e710 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2e720 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2e730 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
2e740 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
2e750 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2e760 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2e770 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
2e780 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
2e790 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
2e7a0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
2e7b0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
2e7c0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2e7d0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
2e7e0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
2e7f0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
2e800 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
2e810 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
2e820 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
2e830 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
2e840 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2e850 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
2e860 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
2e870 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
2e880 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
2e890 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
2e8a0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
2e8b0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
2e8c0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
2e8d0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
2e8e0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
2e8f0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2e900 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
2e910 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
2e920 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
2e930 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2e940 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2e950 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2e960 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2e970 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2e980 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2e990 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e9a0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
2e9b0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2e9c0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2e9d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2e9e0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
2e9f0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
2ea00 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
2ea10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
2ea20 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
2ea30 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
2ea40 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2ea50 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2ea60 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2ea70 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2ea80 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2ea90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
2eaa0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
2eab0 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
2eac0 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
2ead0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2eae0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
2eaf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
2eb00 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2eb10 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
2eb20 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
2eb30 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
2eb40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
2eb50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2eb60 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
2eb70 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
2eb80 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
2eb90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2eba0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
2ebb0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2ebc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
2ebd0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
2ebe0 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
2ebf0 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
2ec00 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
2ec10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ec20 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
2ec30 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
2ec40 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
2ec50 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
2ec60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
2ec70 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2ec80 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
2ec90 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2eca0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
2ecb0 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
2ecc0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
2ecd0 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
2ece0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
2ecf0 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
2ed00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ed10 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
2ed20 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
2ed30 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2ed40 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2ed50 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
2ed60 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
2ed70 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
2ed80 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
2ed90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2eda0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
2edb0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
2edc0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
2edd0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
2ede0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
2edf0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
2ee00 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
2ee10 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
2ee20 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
2ee30 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2ee40 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
2ee50 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
2ee60 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
2ee70 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
2ee80 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
2ee90 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
2eea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2eeb0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
2eec0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
2eed0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
2eee0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2eef0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2ef00 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
2ef10 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
2ef20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2ef30 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
2ef40 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
2ef50 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
2ef60 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
2ef70 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
2ef80 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2ef90 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2efa0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2efb0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
2efc0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2efd0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
2efe0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
2eff0 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
2f000 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
2f010 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2f020 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2f030 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
2f040 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
2f050 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
2f060 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
2f070 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
2f080 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
2f090 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
2f0a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2f0b0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
2f0c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f0d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
2f0e0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
2f0f0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
2f100 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
2f110 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
2f120 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
2f130 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
2f140 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
2f150 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
2f160 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
2f170 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
2f180 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
2f190 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
2f1a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f1b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f1c0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
2f1d0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2f1e0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2f1f0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2f200 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2f210 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2f220 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2f230 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2f240 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2f250 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2f260 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2f270 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2f280 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2f290 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2f2a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2f2b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2f2c0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2f2d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2f2e0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2f2f0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2f300 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2f310 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2f320 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2f330 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2f340 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2f350 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2f360 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2f370 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2f380 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2f390 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2f3a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2f3b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2f3c0 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
2f3d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
2f3e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2f3f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2f400 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2f410 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2f420 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2f430 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2f440 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2f450 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2f460 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2f470 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2f480 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2f490 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2f4a0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2f4b0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2f4c0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2f4d0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
2f4e0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2f4f0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2f500 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2f510 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
2f520 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2f530 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2f540 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2f550 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2f560 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2f570 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2f580 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2f590 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2f5a0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2f5b0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2f5c0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2f5d0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2f5e0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2f5f0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2f600 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2f610 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2f620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2f630 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2f640 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2f650 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f660 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2f670 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2f680 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2f690 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2f6a0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2f6b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f6c0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2f6d0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2f6e0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2f6f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2f700 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2f710 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2f720 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2f730 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2f740 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2f750 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2f760 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2f770 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2f780 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2f790 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2f7a0 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2f7b0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2f7c0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2f7d0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2f7e0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2f7f0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2f800 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2f810 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
2f820 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
2f830 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
2f840 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
2f850 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
2f860 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2f870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f880 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
2f890 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
2f8a0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2f8b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2f8c0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2f8d0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2f8e0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
2f8f0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2f900 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2f910 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2f920 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2f930 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
2f940 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2f950 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
2f960 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
2f970 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
2f980 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f990 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2f9a0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2f9b0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
2f9c0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f9d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
2f9e0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
2f9f0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
2fa00 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
2fa10 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
2fa20 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2fa30 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2fa40 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2fa50 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2fa60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
2fa70 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
2fa80 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
2fa90 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2faa0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
2fab0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
2fac0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
2fad0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
2fae0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
2faf0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
2fb00 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
2fb10 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
2fb20 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
2fb30 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
2fb40 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
2fb50 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
2fb60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fb70 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2fb80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fb90 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
2fba0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
2fbb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2fbc0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
2fbd0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2fbe0 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
2fbf0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
2fc00 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
2fc10 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
2fc20 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
2fc30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2fc40 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
2fc50 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
2fc60 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2fc70 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
2fc80 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
2fc90 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
2fca0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2fcb0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
2fcc0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
2fcd0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2fce0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
2fcf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2fd00 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
2fd10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fd20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2fd30 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
2fd40 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
2fd50 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
2fd60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fd70 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
2fd80 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
2fd90 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2fda0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2fdb0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
2fdc0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
2fdd0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
2fde0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2fdf0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
2fe00 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
2fe10 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
2fe20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fe30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
2fe40 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
2fe50 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
2fe60 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
2fe70 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
2fe80 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
2fe90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fea0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2feb0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2fec0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2fed0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2fee0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2fef0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2ff00 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
2ff10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ff20 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
2ff30 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2ff40 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2ff50 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
2ff60 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
2ff70 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
2ff80 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
2ff90 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
2ffa0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2ffb0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2ffc0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2ffd0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2ffe0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2fff0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
30000 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
30010 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
30020 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
30030 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
30040 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
30050 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
30060 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
30070 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
30080 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
30090 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
300a0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
300b0 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
300c0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
300d0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
300e0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
300f0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
30100 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
30110 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
30120 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
30130 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
30140 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
30150 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
30160 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
30170 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
30180 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
30190 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
301a0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
301b0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
301c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
301d0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
301e0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
301f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
30200 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
30210 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
30220 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
30230 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
30240 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
30250 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
30260 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
30270 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30280 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
302a0 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
302b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
302c0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
302d0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
302e0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
302f0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
30300 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
30310 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
30320 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
30330 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
30340 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
30350 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
30360 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
30370 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30380 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
30390 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
303a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
303b0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
303c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
303d0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
303e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
303f0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
30400 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
30410 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
30420 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
30430 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
30440 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
30450 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
30460 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
30470 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
30480 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
30490 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
304a0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
304b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
304c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
304d0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
304e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
304f0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30500 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
30510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30520 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
30530 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
30540 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
30550 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30560 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
30570 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30580 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
30590 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
305a0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
305b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
305c0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
305d0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
305e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
305f0 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
30600 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
30610 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
30620 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
30630 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
30640 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
30650 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
30660 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
30670 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
30680 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
30690 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
306a0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
306b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
306c0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
306d0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
306e0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
306f0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
30700 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
30710 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
30720 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
30730 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
30740 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
30750 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
30760 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
30770 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
30780 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
30790 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
307a0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
307b0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
307c0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
307d0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
307e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
307f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30800 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
30810 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
30820 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
30830 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
30840 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
30850 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
30860 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
30870 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
30880 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
30890 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
308a0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
308b0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
308c0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
308d0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
308e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
308f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
30900 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
30910 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
30920 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
30930 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
30940 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
30950 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
30960 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
30970 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
30980 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
30990 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
309a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
309b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
309c0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
309d0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
309e0 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
309f0 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
30a00 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
30a10 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
30a20 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
30a30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
30a40 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
30a50 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
30a60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30a70 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
30a80 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
30a90 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
30aa0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
30ab0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
30ac0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
30ad0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
30ae0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
30af0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
30b00 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
30b10 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
30b20 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
30b30 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
30b40 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
30b50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
30b60 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
30b70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
30b80 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
30b90 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
30ba0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30bb0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
30bc0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
30bd0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
30be0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
30bf0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
30c00 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
30c10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
30c20 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
30c30 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
30c40 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
30c50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
30c60 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
30c70 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
30c80 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
30c90 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
30ca0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
30cb0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
30cc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
30cd0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
30ce0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
30cf0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
30d00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
30d10 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
30d20 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
30d30 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30d40 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
30d50 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
30d60 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
30d70 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
30d80 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
30d90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30da0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
30db0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30dc0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
30dd0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
30de0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
30df0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
30e00 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
30e10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
30e20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
30e30 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
30e40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30e50 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
30e60 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
30e70 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
30e80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30e90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
30ea0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
30eb0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
30ec0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
30ed0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
30ee0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
30ef0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30f00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
30f10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
30f20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
30f30 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
30f40 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
30f50 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
30f60 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
30f70 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
30f80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30f90 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
30fa0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
30fb0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
30fc0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
30fd0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
30fe0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
30ff0 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
31000 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
31010 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31020 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
31030 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31040 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
31050 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
31060 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
31070 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
31080 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
31090 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
310a0 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  I sqlite3 *sqlit
310b0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
310c0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
310d0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
310e0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
310f0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
31100 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
31110 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
31120 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
31130 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
31140 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
31150 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
31160 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
31170 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
31180 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
31190 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
311a0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
311b0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
311c0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
311d0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
311e0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
311f0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
31200 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
31210 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
31220 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
31230 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
31240 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
31250 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
31260 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
31270 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
31280 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
31290 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
312a0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
312b0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
312c0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
312d0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
312e0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
312f0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
31300 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
31310 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
31320 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
31330 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
31340 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
31350 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
31360 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
31370 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
31380 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
31390 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
313a0 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
313b0 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
313c0 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
313d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
313e0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
313f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31400 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
31410 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
31420 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
31430 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
31440 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
31450 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
31460 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
31470 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31480 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
31490 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
314a0 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
314b0 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
314c0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
314d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
314e0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
314f0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
31500 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
31510 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
31520 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
31530 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
31540 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31550 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
31560 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
31570 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31580 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
31590 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
315a0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
315b0 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
315c0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
315d0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
315e0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
315f0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
31600 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31610 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
31620 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
31630 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
31640 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
31650 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
31660 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
31670 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
31680 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
31690 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
316a0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
316b0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
316c0 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
316d0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
316e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
316f0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
31700 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
31710 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
31720 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
31730 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
31740 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
31750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
31760 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
31770 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
31780 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
31790 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
317a0 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
317b0 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
317c0 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
317d0 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
317e0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
317f0 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
31800 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
31810 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
31820 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
31830 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
31840 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
31850 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
31860 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
31870 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
31880 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
31890 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
318a0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
318b0 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
318c0 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
318d0 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
318e0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
318f0 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
31900 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
31910 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
31920 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
31930 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
31940 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
31950 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
31960 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
31970 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31980 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
31990 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  xt*, int N);.SQL
319a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
319b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
319c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
319d0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
319e0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
319f0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
31a00 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
31a10 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
31a20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
31a30 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
31a40 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
31a50 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
31a60 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
31a70 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
31a80 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
31a90 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
31aa0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31ab0 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
31ac0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
31ad0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
31ae0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
31af0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
31b00 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
31b10 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
31b20 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
31b30 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
31b40 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
31b50 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
31b60 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
31b70 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
31b80 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
31b90 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
31ba0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
31bb0 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
31bc0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
31bd0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
31be0 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
31bf0 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
31c00 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
31c10 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
31c20 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
31c30 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
31c40 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
31c50 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
31c60 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
31c70 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
31c80 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
31c90 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
31ca0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
31cb0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
31cc0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
31cd0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
31ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
31cf0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
31d00 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
31d10 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
31d20 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
31d30 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
31d40 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
31d50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
31d60 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
31d70 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
31d80 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
31d90 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
31da0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
31db0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
31dc0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
31dd0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
31de0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31df0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
31e00 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
31e10 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
31e20 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
31e30 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
31e40 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
31e50 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
31e60 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
31e70 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
31e80 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
31e90 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
31ea0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
31eb0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
31ec0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
31ed0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
31ee0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
31ef0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
31f00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
31f10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
31f20 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
31f30 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
31f40 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
31f50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31f60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
31f70 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
31f80 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
31f90 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
31fa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
31fb0 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
31fc0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
31fd0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
31fe0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
31ff0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32000 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
32010 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
32020 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
32030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32040 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32050 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
32060 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
32070 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
32080 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
32090 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
320a0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
320b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
320c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
320d0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
320e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
320f0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
32100 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
32110 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32120 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
32130 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
32140 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
32150 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
32160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32170 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32180 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
32190 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
321a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
321b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
321c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
321d0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
321e0 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
321f0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
32200 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
32210 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
32220 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
32230 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
32240 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32250 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
32260 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
32270 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
32280 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
32290 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
322a0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
322b0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
322c0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
322d0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
322e0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
322f0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
32300 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32310 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
32320 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
32330 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
32340 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
32350 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32360 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
32370 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32380 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
32390 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
323a0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
323b0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
323c0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
323d0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
323e0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
323f0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
32400 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
32410 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
32420 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
32430 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
32440 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
32450 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
32460 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
32470 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
32480 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
32490 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
324a0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
324b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
324c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
324d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
324e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
324f0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
32500 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
32510 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
32520 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
32530 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
32540 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
32550 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
32560 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
32570 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
32580 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
32590 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
325a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
325b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
325c0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
325d0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
325e0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
325f0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
32600 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
32610 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
32620 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
32630 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
32640 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
32650 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
32660 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
32670 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32680 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
32690 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
326a0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
326b0 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
326c0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
326d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
326e0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
326f0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
32700 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
32710 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
32720 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
32730 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
32740 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
32750 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
32760 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32770 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
32780 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
32790 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
327a0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
327b0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
327c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
327d0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
327e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
327f0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
32800 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
32810 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
32820 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32830 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32840 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
32850 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
32860 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
32870 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
32880 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
32890 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
328a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
328b0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
328c0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
328d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
328e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
328f0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
32900 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
32910 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
32920 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
32930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32940 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
32950 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
32960 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
32970 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
32980 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32990 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
329a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
329b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
329c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
329d0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
329e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
329f0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
32a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32a10 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
32a20 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
32a30 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
32a40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32a50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32a60 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
32a70 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
32a80 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
32a90 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
32aa0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
32ab0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
32ac0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
32ad0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
32ae0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
32af0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
32b00 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
32b10 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
32b20 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
32b30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
32b40 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
32b50 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
32b60 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
32b70 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
32b80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
32b90 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
32ba0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
32bb0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
32bc0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
32bd0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
32be0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
32bf0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
32c00 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
32c10 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
32c20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
32c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32c40 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
32c50 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
32c60 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
32c70 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
32c80 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
32c90 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
32ca0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
32cb0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
32cc0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
32cd0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
32ce0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
32cf0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
32d00 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
32d10 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
32d20 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
32d30 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
32d40 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
32d50 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
32d60 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
32d70 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
32d80 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
32d90 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
32da0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
32db0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
32dc0 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
32dd0 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
32de0 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
32df0 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
32e00 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
32e10 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
32e20 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
32e30 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
32e40 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
32e50 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
32e60 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
32e70 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
32e80 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
32e90 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
32ea0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
32eb0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
32ec0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
32ed0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
32ee0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
32ef0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
32f00 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
32f10 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
32f20 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
32f30 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
32f40 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
32f50 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
32f60 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
32f70 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
32f80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
32f90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
32fa0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32fb0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
32fc0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
32fd0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
32fe0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
32ff0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
33000 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
33010 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
33020 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
33030 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
33040 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
33050 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
33060 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
33070 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
33080 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
33090 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
330a0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
330b0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
330c0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
330d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
330e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
330f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33100 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33110 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
33120 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
33130 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
33140 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
33150 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
33160 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
33170 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
33180 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
33190 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
331a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
331b0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
331c0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
331d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
331e0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
331f0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
33200 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
33210 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33220 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
33230 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
33240 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
33250 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
33260 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
33270 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
33280 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
33290 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
332a0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
332b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
332c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
332d0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
332e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
332f0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
33300 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
33310 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
33320 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
33330 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
33340 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
33350 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
33360 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
33370 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33380 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
33390 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
333a0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
333b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
333c0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
333d0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
333e0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
333f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
33400 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
33410 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
33420 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
33430 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
33440 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
33450 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
33460 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
33470 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
33480 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33490 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
334a0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
334b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
334c0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
334d0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
334e0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
334f0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
33500 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
33510 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33520 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33530 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
33540 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
33550 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33560 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
33570 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
33580 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
33590 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
335a0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
335b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
335c0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53  t char*, int);.S
335d0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
335e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
335f0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
33600 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
33610 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
33620 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
33630 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33640 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
33650 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
33660 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33670 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
33680 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
33690 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
336a0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
336b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
336c0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
336d0 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
336e0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
336f0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
33700 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33710 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
33720 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33730 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
33740 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
33750 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
33760 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
33770 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
33780 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33790 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
337a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
337b0 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
337c0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
337d0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
337e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
337f0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
33800 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33810 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
33820 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
33830 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
33840 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
33850 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
33860 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
33870 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33880 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33890 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
338a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
338b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
338c0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
338d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
338e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
338f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
33900 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33910 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
33920 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
33930 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
33940 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
33950 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
33960 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
33970 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33980 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
33990 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
339a0 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
339b0 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
339c0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
339d0 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
339e0 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
339f0 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
33a00 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
33a10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33a20 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
33a30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33a40 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
33a50 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
33a60 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
33a70 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
33a80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33a90 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
33aa0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33ab0 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
33ac0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
33ad0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
33ae0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
33af0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33b00 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
33b10 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
33b20 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
33b30 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
33b40 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
33b50 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
33b60 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
33b70 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
33b80 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
33b90 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
33ba0 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
33bb0 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
33bc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
33bd0 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
33be0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
33bf0 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
33c00 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
33c10 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
33c20 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
33c30 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
33c40 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
33c50 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
33c60 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
33c70 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
33c80 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
33c90 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
33ca0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
33cb0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
33cc0 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
33cd0 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
33ce0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
33cf0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
33d00 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
33d10 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
33d20 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
33d30 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
33d40 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
33d50 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
33d60 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
33d70 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
33d80 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
33d90 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
33da0 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
33db0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
33dc0 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
33dd0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
33de0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
33df0 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
33e00 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
33e10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
33e20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
33e30 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
33e40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
33e50 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
33e60 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
33e70 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
33e80 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
33e90 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
33ea0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
33eb0 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
33ec0 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
33ed0 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
33ee0 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
33ef0 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
33f00 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
33f10 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
33f20 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
33f30 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
33f40 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
33f50 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
33f60 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
33f70 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
33f80 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
33f90 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
33fa0 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
33fb0 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
33fc0 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
33fd0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
33fe0 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
33ff0 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
34000 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
34010 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
34020 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34030 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
34040 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
34050 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
34060 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
34070 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
34080 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
34090 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
340a0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
340b0 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
340c0 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
340d0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
340e0 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
340f0 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
34100 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
34110 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
34120 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
34130 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
34140 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
34150 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
34160 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
34170 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
34180 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34190 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
341a0 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
341b0 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
341c0 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
341d0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
341e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
341f0 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
34200 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
34210 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
34220 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
34230 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
34240 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
34250 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
34260 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
34270 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
34280 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
34290 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
342a0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
342b0 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
342c0 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
342d0 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
342e0 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
342f0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
34300 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
34310 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
34320 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
34330 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
34340 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
34350 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
34360 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
34370 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
34380 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
34390 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
343a0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
343b0 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
343c0 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
343d0 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
343e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
343f0 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
34400 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
34410 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
34420 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
34430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34440 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34450 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
34460 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
34470 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
34480 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
34490 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
344a0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
344b0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
344c0 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
344d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
344e0 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
344f0 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
34500 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
34510 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
34520 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
34530 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
34540 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
34550 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
34560 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
34570 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34580 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
34590 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
345a0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
345b0 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
345c0 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
345d0 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
345e0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
345f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34600 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
34610 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
34620 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
34630 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34640 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
34650 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
34660 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
34670 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
34680 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
34690 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
346a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
346b0 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
346c0 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
346d0 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
346e0 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
346f0 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
34700 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
34710 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
34720 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
34730 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
34740 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
34750 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
34760 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
34770 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
34780 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
34790 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
347a0 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
347b0 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
347c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
347d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
347e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
347f0 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  6()]..*/.SQLITE_
34800 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34810 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34820 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
34830 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
34840 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
34850 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
34860 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
34870 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
34880 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
34890 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53  onst void*).);.S
348a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
348b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
348c0 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
348d0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
348e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
348f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
34900 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
34910 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
34920 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
34930 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
34940 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
34950 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
34960 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34970 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34980 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
34990 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
349a0 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
349b0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
349c0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
349d0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
349e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
349f0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
34a00 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
34a10 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
34a20 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
34a30 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
34a40 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
34a50 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
34a60 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
34a70 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
34a80 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
34a90 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
34aa0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
34ab0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
34ac0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
34ad0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34ae0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
34af0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
34b00 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
34b10 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
34b20 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
34b30 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
34b40 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
34b50 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
34b60 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34b70 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
34b80 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
34b90 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
34ba0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
34bb0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
34bc0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
34bd0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
34be0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34bf0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
34c00 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
34c10 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
34c20 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
34c30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
34c40 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
34c50 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
34c60 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
34c70 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
34c80 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
34c90 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
34ca0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34cb0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
34cc0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
34cd0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
34ce0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
34cf0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
34d00 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34d10 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
34d20 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34d30 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
34d40 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
34d50 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
34d60 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
34d70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
34d80 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
34d90 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
34da0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
34db0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
34dc0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
34dd0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
34de0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
34df0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
34e00 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34e10 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
34e20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
34e30 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
34e40 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
34e50 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
34e60 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
34e70 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
34e80 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
34e90 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
34ea0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34eb0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34ec0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
34ed0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34ee0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
34ef0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34f00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
34f10 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34f20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34f30 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
34f40 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
34f50 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
34f60 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
34f70 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
34f80 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  ar*).);.SQLITE_A
34f90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
34fa0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
34fb0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
34fc0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
34fd0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
34fe0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
34ff0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
35000 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
35010 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
35020 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
35030 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
35040 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
35050 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
35060 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
35070 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
35080 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
35090 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
350a0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
350b0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
350c0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
350d0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
350e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
350f0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
35100 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
35110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35120 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
35130 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
35140 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
35150 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
35160 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
35170 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
35180 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
35190 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
351a0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
351b0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
351c0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
351d0 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
351e0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
351f0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
35200 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
35210 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
35220 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
35230 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
35240 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
35250 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
35260 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
35270 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
35280 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
35290 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
352a0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
352b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
352c0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
352d0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
352e0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
352f0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
35300 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
35310 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
35320 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
35330 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
35340 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
35350 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
35360 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
35370 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
35380 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35390 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
353a0 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
353b0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
353c0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
353d0 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
353e0 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
353f0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
35400 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
35410 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
35420 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
35430 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
35440 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
35450 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
35460 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
35470 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49  ll work..*/.SQLI
35480 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
35490 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
354a0 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
354b0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
354c0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
354d0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
354e0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
354f0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
35500 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
35510 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
35520 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
35530 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
35540 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
35550 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
35560 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
35570 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
35580 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
35590 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
355a0 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
355b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
355c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
355d0 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
355e0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
355f0 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
35600 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
35610 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
35620 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
35630 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
35640 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
35650 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
35660 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
35670 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
35680 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
35690 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
356a0 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
356b0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
356c0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
356d0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
356e0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
356f0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
35700 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
35710 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
35720 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
35730 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
35740 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
35750 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
35760 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
35770 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
35780 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
35790 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
357a0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
357b0 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
357c0 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
357d0 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
357e0 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
357f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
35800 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
35810 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
35820 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
35830 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
35840 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
35850 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
35860 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
35870 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
35880 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
35890 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
358a0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
358b0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
358c0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
358d0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
358e0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
358f0 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
35900 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
35910 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
35920 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
35930 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
35940 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
35950 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
35960 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
35970 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
35980 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
35990 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
359a0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
359b0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
359c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
359d0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
359e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
359f0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
35a00 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
35a10 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
35a20 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35a30 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35a40 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
35a50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35a60 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
35a70 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
35a80 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
35a90 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
35aa0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
35ab0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
35ac0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
35ad0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
35ae0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
35af0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
35b00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
35b10 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
35b20 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
35b30 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
35b40 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
35b50 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
35b60 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
35b70 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35b80 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
35b90 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
35ba0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
35bb0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
35bc0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
35bd0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35be0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
35bf0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
35c00 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35c10 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
35c20 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
35c30 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
35c40 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
35c50 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
35c60 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
35c70 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
35c80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
35c90 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
35ca0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
35cb0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
35cc0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
35cd0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
35ce0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
35cf0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
35d00 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
35d10 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
35d20 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
35d30 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
35d40 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
35d50 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
35d60 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
35d70 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
35d80 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35d90 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
35da0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
35db0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
35dc0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
35dd0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
35de0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
35df0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
35e00 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
35e10 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ling [sqlite3_op
35e20 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  en] or [sqlite3_
35e30 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72  open_v2].  Other
35e40 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
35e50 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
35e60 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
35e70 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
35e80 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72  s may fail.  Her
35e90 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70  e is an.** examp
35ea0 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20  le of how to do 
35eb0 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77  this using C++ w
35ec0 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20  ith the Windows 
35ed0 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c  Runtime:.**.** <
35ee0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
35ef0 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74  .** LPCWSTR zPat
35f00 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f  h = Windows::Sto
35f10 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f  rage::Applicatio
35f20 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e  nData::Current->
35f30 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54  .** &nbsp;     T
35f40 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e  emporaryFolder->
35f50 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a  Path->Data();.**
35f60 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23   char zPathBuf&#
35f70 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26  91;MAX_PATH + 1&
35f80 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28  #93;;.** memset(
35f90 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a  zPathBuf, 0, siz
35fa0 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a  eof(zPathBuf));.
35fb0 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c  ** WideCharToMul
35fc0 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20  tiByte(CP_UTF8, 
35fd0 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50  0, zPath, -1, zP
35fe0 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a  athBuf, sizeof(z
35ff0 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62  PathBuf),.** &nb
36000 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55  sp;     NULL, NU
36010 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  LL);.** sqlite3_
36020 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d  temp_directory =
36030 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
36040 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29  ("%s", zPathBuf)
36050 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
36060 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49  ckquote>.*/.SQLI
36070 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
36080 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
36090 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
360a0 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
360b0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
360c0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
360d0 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
360e0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
360f0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
36100 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
36110 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
36120 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
36130 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
36140 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
36150 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
36160 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
36170 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
36180 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
36190 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
361a0 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
361b0 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
361c0 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
361d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
361e0 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
361f0 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
36200 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
36210 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
36220 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
36230 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
36240 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
36250 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
36260 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
36270 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
36280 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
36290 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
362a0 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
362b0 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
362c0 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
362d0 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
362e0 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
362f0 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
36300 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
36310 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
36320 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
36330 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
36340 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
36350 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
36360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36370 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
36380 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
36390 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
363a0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
363b0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
363c0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
363d0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
363e0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
363f0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
36400 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
36410 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
36420 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
36430 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36440 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
36450 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
36460 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
36470 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
36480 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
36490 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
364a0 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
364b0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
364c0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
364d0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
364e0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
364f0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
36500 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
36510 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
36520 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
36530 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
36540 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
36550 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
36560 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36570 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
36580 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
36590 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
365a0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
365b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
365c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
365d0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
365e0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
365f0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36600 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
36610 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
36620 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
36630 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
36640 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
36650 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
36660 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
36670 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
36680 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
36690 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
366a0 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
366b0 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
366c0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
366d0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
366e0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
366f0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
36700 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
36710 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
36720 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
36730 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
36740 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
36750 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
36760 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
36770 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36780 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
36790 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
367a0 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
367b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
367c0 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
367d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
367e0 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
367f0 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
36800 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
36810 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
36820 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
36830 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
36840 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
36850 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
36860 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
36870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36880 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
36890 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
368a0 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
368b0 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
368c0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
368d0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
368e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
368f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
36900 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
36910 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
36920 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
36930 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
36940 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
36950 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
36960 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
36970 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
36980 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
36990 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
369a0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
369b0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
369c0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
369d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
369e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
369f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
36a00 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
36a10 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
36a20 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
36a30 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
36a40 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
36a50 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
36a60 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
36a70 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
36a80 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
36a90 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
36aa0 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
36ab0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
36ac0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
36ad0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
36ae0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
36af0 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
36b00 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
36b10 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36b20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
36b30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
36b40 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
36b50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
36b60 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
36b70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
36b80 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
36b90 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
36ba0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
36bb0 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
36bc0 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
36bd0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
36be0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
36bf0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
36c00 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
36c10 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
36c20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36c30 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
36c40 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
36c50 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
36c60 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61  s.  ^The [databa
36c70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
36c80 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
36c90 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
36ca0 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
36cb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36cc0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68  ].** that was th
36cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
36ce0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
36cf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
36d00 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
36d10 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
36d20 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
36d30 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
36d40 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
36d50 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lace..*/.SQLITE_
36d60 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
36d70 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
36d80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
36d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36da0 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e  Return The Filen
36db0 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61  ame For A Databa
36dc0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
36dd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36de0 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e  _db_filename(D,N
36df0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36e00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36e10 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61   a filename.** a
36e20 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64  ssociated with d
36e30 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e  atabase N of con
36e40 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65  nection D.  ^The
36e50 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
36e60 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e  ile.** has the n
36e70 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20  ame "main".  If 
36e80 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61  there is no atta
36e90 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20  ched database N 
36ea0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  on the database.
36eb0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  ** connection D,
36ec0 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20   or if database 
36ed0 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79  N is a temporary
36ee0 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61   or in-memory da
36ef0 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20  tabase, then.** 
36f00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
36f10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36f20 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  * ^The filename 
36f30 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
36f40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
36f50 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a   output of the.*
36f60 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20  * xFullPathname 
36f70 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56  method of the [V
36f80 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20  FS].  ^In other 
36f90 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e  words, the filen
36fa0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61  ame.** will be a
36fb0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e  n absolute pathn
36fc0 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65  ame, even if the
36fd0 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a   filename used.*
36fe0 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  * to open the da
36ff0 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c  tabase originall
37000 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72  y was a URI or r
37010 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
37020 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37030 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
37040 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
37050 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
37060 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
37070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37080 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66  EF: Determine if
37090 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72   a database is r
370a0 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e  ead-only.**.** ^
370b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  The sqlite3_db_r
370c0 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74  eadonly(D,N) int
370d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31  erface returns 1
370e0 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
370f0 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74   N.** of connect
37100 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e  ion D is read-on
37110 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72  ly, 0 if it is r
37120 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31  ead/write, or -1
37130 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20   if N is not.** 
37140 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61  the name of a da
37150 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63  tabase on connec
37160 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49 54  tion D..*/.SQLIT
37170 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37180 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71  3_db_readonly(sq
37190 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
371a0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
371b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
371c0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
371d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
371e0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
371f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37200 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
37210 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
37220 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
37230 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
37240 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
37250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37260 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
37270 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
37280 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
37290 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
372a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
372b0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
372c0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
372d0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
372e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
372f0 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
37300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37310 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
37320 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
37330 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
37340 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
37350 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
37360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
37370 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
37380 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
37390 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
373a0 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
373b0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
373c0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
373d0 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
373e0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
373f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
37400 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
37410 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
37420 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
37430 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
37440 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
37450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37460 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
37470 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
37480 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
37490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
374a0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
374b0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
374c0 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
374d0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
374e0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
374f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
37500 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
37510 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ed]..** ^Any cal
37520 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
37530 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
37540 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37550 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
37560 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
37570 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
37580 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
37590 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
375a0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
375b0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
375c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
375d0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
375e0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
375f0 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c  nsaction is [ROL
37600 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62  LBACK | rolled b
37610 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ack]..** ^Any ca
37620 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
37630 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
37640 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
37650 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  k_hook().** for 
37660 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37680 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
37690 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
376a0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
376b0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
376c0 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ack..** ^If the 
376d0 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
376e0 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
376f0 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
37700 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
37710 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
37720 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
37730 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
37740 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
37750 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20  hook(D,C,P) and 
37760 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37770 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
37780 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
37790 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
377a0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
377b0 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61  s call of the sa
377c0 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f  me function.** o
377d0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
377e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
377f0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
37800 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
37810 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74  l for each funct
37820 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ion on D..**.** 
37830 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72  The commit and r
37840 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c  ollback hook cal
37850 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72  lbacks are not r
37860 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65  eentrant..** The
37870 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
37880 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
37890 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
378a0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
378b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
378c0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
378d0 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
378e0 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
378f0 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
37900 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37910 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
37920 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
37930 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
37940 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
37950 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
37960 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
37970 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
37980 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
37990 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
379a0 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
379b0 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74  t running any ot
379c0 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  her SQL statemen
379d0 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45  ts, including SE
379e0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c  LECT statements,
379f0 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61  .** or merely ca
37a00 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
37a10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
37a20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
37a30 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  ] will modify.**
37a40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37a50 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
37a60 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
37a70 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
37a80 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
37a90 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
37aa0 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
37ab0 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
37ac0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74  k..**.** ^When t
37ad0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
37ae0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
37af0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
37b00 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70  e [COMMIT].** op
37b10 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77  eration is allow
37b20 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e  ed to continue n
37b30 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68  ormally.  ^If th
37b40 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a  e commit hook.**
37b50 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
37b60 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d  o, then the [COM
37b70 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65  MIT] is converte
37b80 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41  d into a [ROLLBA
37b90 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  CK]..** ^The rol
37ba0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e  lback hook is in
37bb0 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62  voked on a rollb
37bc0 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73  ack that results
37bd0 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a   from a commit.*
37be0 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67  * hook returning
37bf0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20   non-zero, just 
37c00 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77  as it would be w
37c10 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f  ith any other ro
37c20 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46  llback..**.** ^F
37c30 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
37c40 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
37c50 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
37c60 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a  id to have been.
37c70 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
37c80 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
37c90 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
37ca0 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
37cb0 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
37cc0 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
37cd0 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
37ce0 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
37cf0 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  r..** ^The rollb
37d00 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
37d10 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
37d20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
37d30 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
37d40 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
37d50 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
37d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37d70 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  closed..**.** Se
37d80 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
37d90 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37da0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
37db0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37dc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
37dd0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
37de0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
37df0 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
37e00 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
37e10 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
37e20 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
37e30 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
37e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37e50 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
37e60 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
37e70 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
37e80 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37e90 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
37ea0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
37eb0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
37ec0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
37ed0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37ee0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
37ef0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
37f00 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
37f10 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
37f20 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
37f30 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
37f40 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
37f50 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
37f60 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
37f70 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f  s function.** fo
37f80 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
37f90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
37fa0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
37fb0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
37fc0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
37fd0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
37fe0 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
37ff0 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73  when a.** row is
38000 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
38010 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
38020 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
38030 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
38040 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
38050 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
38060 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
38070 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
38080 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  )..** ^The secon
38090 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
380a0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
380b0 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
380c0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
380d0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
380e0 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
380f0 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
38100 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
38110 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
38120 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
38130 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
38140 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
38150 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
38160 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
38170 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
38180 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
38190 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
381a0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
381b0 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61  ** ^The final ca
381c0 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
381d0 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
381e0 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e  of the row..** ^
381f0 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
38200 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
38210 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66  s the [rowid] af
38220 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74  ter the update t
38230 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
38240 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68  * ^(The update h
38250 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
38260 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
38270 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
38280 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
38290 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
382a0 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
382b0 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a  quence).)^.**.**
382c0 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74   ^In the current
382d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
382e0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
382f0 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  .** is not invok
38300 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74  ed when duplicat
38310 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  ion rows are del
38320 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20  eted because of 
38330 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49  an.** [ON CONFLI
38340 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  CT | ON CONFLICT
38350 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65   REPLACE] clause
38360 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75  .  ^Nor is the u
38370 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e  pdate hook.** in
38380 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20  voked when rows 
38390 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e  are deleted usin
383a0 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20  g the [truncate 
383b0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a  optimization]..*
383c0 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73  * The exceptions
383d0 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73   defined in this
383e0 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74   paragraph might
383f0 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
38400 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
38410 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
38420 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
38430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
38440 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
38450 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
38460 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
38470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38480 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
38490 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41   update hook.  A
384a0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
384b0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
384c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
384d0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
384e0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
384f0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
38500 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
38510 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
38520 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75   triggered the u
38530 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e  pdate hook..** N
38540 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
38550 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
38560 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
38570 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
38580 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
38590 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
385a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
385b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
385c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
385d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
385e0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43  _update_hook(D,C
385f0 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ,P) function.** 
38600 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
38610 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
38620 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a  previous call.**
38630 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
38640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38650 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
38660 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
38670 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  all on D..**.** 
38680 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
38690 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
386a0 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  k()] and [sqlite
386b0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
386c0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  )].** interfaces
386d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
386e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
386f0 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
38700 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
38710 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
38720 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
38730 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
38740 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
38750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38760 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
38770 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
38780 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 5e  er Cache.**.** ^
38790 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
387a0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
387b0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
387c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
387d0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
387e0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65