/ Hex Artifact Content
Login

Artifact 696ecfc764a32b47daaaf0e10438ff2aaa0739e0:


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 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5600: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5610: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5620: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5640: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5650: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5660: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5680: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5690: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
56a0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
56c0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
56e0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5700: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
5710: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5720: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
5730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5740: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5750: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5760: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5780: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5790: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
57a0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
57b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57c0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
57d0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
57e0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
57f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5800: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5810: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5820: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5830: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5840: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5850: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5860: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5890: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
58a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
58b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
58c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
58d0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
58e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
58f0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5910: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5920: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5930: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5940: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5950: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5960: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5990: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59a0: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59c0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
59d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
59e0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
59f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a00: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a20: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5a30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a40: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5a50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a60: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a70: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5aa0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ab0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5ad0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5ae0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5af0: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5b00: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5b10: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b20: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5b30: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5b40: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5b50: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (2<<8))../*.**
5b60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5b70: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5b80: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5b90: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5ba0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5bb0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5bc0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5bd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5be0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5bf0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5c00: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5c10: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
5c20: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
5c30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5c40: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5c50: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5c60: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
5c70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5c80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5c90: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5ca0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5cb0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
5cc0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5cd0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5ce0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d00: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
5d10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5d20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5d30: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5d40: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5d50: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
5d60: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5d70: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5d80: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5d90: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
5da0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5db0: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
5dc0: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
5dd0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
5de0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5df0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
5e00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e10: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e30: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e40: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
5e50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e60: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
5e70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5ea0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5eb0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
5ec0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ef0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
5f00: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f10: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5f20: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5f30: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
5f40: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5f60: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5f70: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
5f80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5fa0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5fb0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
5fc0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5fd0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5fe0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
5ff0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
6000: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
6030: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
6040: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6050: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
6060: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6070: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
6080: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6090: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60a0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
60b0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
60c0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60f0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
6100: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
6110: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6140: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
6150: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
6160: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6180: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6190: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
61a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
61b0: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
61c0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
61d0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
61e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
61f0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
6200: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
6210: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
6220: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6230: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6240: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6260: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6270: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6280: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6290: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
62a0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
62b0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
62c0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
62d0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
62e0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
62f0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6300: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6310: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6320: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6340: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6350: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6360: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6370: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
63a0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
63b0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
63c0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
63d0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
63e0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
63f0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6400: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6410: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6420: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6430: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6440: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6450: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6460: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6470: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6480: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6490: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
64a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
64b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
64c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
64d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
64e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
64f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6500: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6510: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6520: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6530: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6540: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6550: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6560: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6570: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6580: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6590: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
65a0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
65b0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
65c0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
65d0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
65e0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
65f0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6600: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6610: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6620: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6630: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6640: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6650: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6660: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6670: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6680: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
6690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
66a0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
66b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
66c0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
66d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66e0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
66f0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6710: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6720: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6730: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6740: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6760: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6770: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6780: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6790: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
67a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
67c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
67d0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67f0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6800: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6840: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6870: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6890: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68b0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
68d0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
68e0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6900: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6910: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6940: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6950: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
6960: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6970: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6980: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6990: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
69a0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
69b0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
69c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
69d0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
69e0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
69f0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6a00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6a10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6a20: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6a30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6a40: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6a60: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6a80: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6a90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6aa0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6ab0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6ac0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6ad0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6af0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6b00: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6b10: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6b20: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6b30: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6b40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6b50: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6b60: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6b70: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6b80: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6b90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6ba0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6bb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6bc0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6bd0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6be0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6bf0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6c00: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6c10: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6c20: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6c30: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6c40: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6c50: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6c60: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6c70: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6c80: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6c90: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6ca0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6cb0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6cc0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6cd0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6ce0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6cf0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6d00: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6d10: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6d20: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6d30: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6d40: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d50: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6d60: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6d70: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
6d80: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6d90: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6da0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6db0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6dc0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6dd0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6de0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6df0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6e00: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6e10: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6e20: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
6e30: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
6e40: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
6e50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6e60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6e70: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6e80: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6e90: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6ea0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6eb0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6ec0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6ed0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6ee0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6ef0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6f00: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6f10: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6f20: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6f30: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
6f40: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
6f50: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
6f60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6f70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6f80: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6f90: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6fa0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6fb0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6fc0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6fd0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6fe0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7000: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7010: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7020: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7030: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7040: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7050: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7060: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7070: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7080: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7090: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
70a0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
70b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
70c0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
70d0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
70e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
70f0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7100: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7110: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7120: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7130: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7140: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7150: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7160: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7170: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7180: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7190: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
71a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
71b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
71c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
71d0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
71e0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
71f0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7200: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7210: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7220: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7230: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7240: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7250: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7260: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7270: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7280: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7290: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
72a0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
72b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
72c0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
72d0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
72e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
72f0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7300: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7310: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7320: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7330: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7340: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7350: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7360: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7370: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7380: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
73a0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
73b0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
73c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
73d0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
73e0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
73f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7400: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7410: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7430: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7440: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7450: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7460: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7470: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7480: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7490: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
74a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
74b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
74c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
74d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
74e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
74f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7500: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7510: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7520: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7530: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7540: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7550: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7560: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7570: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7580: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7590: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
75a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
75b0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
75c0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
75d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
75e0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
75f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7610: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7620: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7630: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7640: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7650: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7660: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7670: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7680: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7690: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
76a0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
76b0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
76c0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
76d0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
76e0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
76f0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7700: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7710: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7720: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7730: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7740: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7750: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7760: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7770: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7780: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7790: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
77a0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
77b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
77c0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
77d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
77e0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
77f0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7800: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7810: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7820: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7830: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7840: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7850: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7860: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7870: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7880: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7890: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
78a0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
78b0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
78c0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
78d0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
78e0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
78f0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7900: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7910: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7920: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7930: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7940: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7950: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7960: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7970: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7980: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7990: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
79a0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
79b0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
79c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
79d0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
79e0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
79f0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7a00: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7a10: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7a20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7a30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7a40: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7a50: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7a60: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7a70: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7a80: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7a90: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7aa0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7ab0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7ac0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7ad0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7ae0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7af0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7b00: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7b10: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7b20: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7b30: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7b40: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7b50: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7b60: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7b70: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7b80: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7b90: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7ba0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7bb0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7bc0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7bd0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7be0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7bf0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7c00: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7c10: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7c20: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7c30: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7c40: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7c50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7c60: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7c70: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7c80: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7c90: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7ca0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7cb0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7cc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7cd0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7ce0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7cf0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7d00: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7d10: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7d20: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7d30: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7d40: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7d50: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7d60: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7d70: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7d80: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7d90: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7da0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7db0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7dc0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7dd0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7de0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7df0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7e00: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7e10: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7e20: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7e30: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7e40: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7e50: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7e70: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7e80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7e90: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7eb0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7ec0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ed0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7ee0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ef0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f10: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f30: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f50: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7f60: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f70: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7f80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7f90: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7fa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7fb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7fc0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7fd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7fe0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7ff0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
8000: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
8010: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8020: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8030: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8040: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8050: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8060: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8070: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8080: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8090: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
80a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
80b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
80c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
80d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
80e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
80f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8100: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8110: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8120: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8130: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8140: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8150: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8160: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8170: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8180: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8190: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
81a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
81b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
81c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
81d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
81e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
81f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8200: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8210: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8220: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8230: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8240: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8250: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8260: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8270: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8280: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8290: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
82a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
82b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
82c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
82d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
82e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
82f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8300: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8310: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8320: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8330: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8350: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8360: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8370: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8380: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
83a0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
83b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
83c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
83d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
83e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
83f0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8400: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8410: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8420: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8430: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8440: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8450: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8460: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8470: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8480: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8490: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
84a0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
84b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
84c0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
84d0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
84e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
84f0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8510: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8520: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8530: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8540: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8550: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8560: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8570: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8580: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8590: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
85a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85b0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
85c0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
85d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
85f0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8600: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8610: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8620: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8630: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8640: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8650: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8660: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8670: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8680: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8690: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
86a0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
86b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
86c0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
86d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
86e0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
86f0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8700: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8710: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8720: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8730: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8740: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8750: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8760: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8770: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8780: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8790: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
87a0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
87b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
87c0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
87d0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
87e0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
87f0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8800: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8810: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8820: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8830: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8840: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
8850: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8860: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8870: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8880: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8890: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
88a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
88b0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
88c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
88d0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
88e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
88f0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8900: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8910: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8920: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8930: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8940: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8950: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8960: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8970: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8980: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8990: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
89a0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
89b0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
89c0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
89d0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
89e0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
89f0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8a00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8a10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8a20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8a30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8a40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8a50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8a60: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8a70: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8a80: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8a90: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8aa0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8ac0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8ad0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8ae0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8af0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8b00: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8b10: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8b20: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8b30: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8b40: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8b50: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8b60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8b70: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8b80: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8b90: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8ba0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8bb0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8bc0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8bd0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8be0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8bf0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8c00: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8c10: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8c20: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8c30: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8c40: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8c50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8c60: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8c70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8c80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8c90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8ca0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8cb0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8cc0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8cd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8ce0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
8cf0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
8d00: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
8d10: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
8d20: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8d30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8d40: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
8d50: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
8d60: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
8d70: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
8d80: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
8d90: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
8da0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
8db0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
8dc0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
8dd0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
8de0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
8df0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
8e00: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
8e10: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
8e20: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
8e30: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
8e40: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
8e50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8e60: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
8e70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8e80: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8e90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ea0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
8eb0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8ec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8ed0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8ee0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8ef0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8f00: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8f20: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8f30: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8f40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8f50: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
8f60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8f70: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
8f80: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
8f90: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8fa0: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20  TTED] opcode is 
8fb0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
8fc0: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ally by.** SQLit
8fd0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c  e and sent to al
8fe0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65  l VFSes in place
8ff0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68   of a call to th
9000: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a  e xSync method.*
9010: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  * when the datab
9020: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
9030: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  as [PRAGMA synch
9040: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f  ronous] set to O
9050: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70  FF.)^.** Some sp
9060: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9070: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9080: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65   in order to ope
9090: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a  rate correctly.*
90a0: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73  * when [PRAGMA s
90b0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
90c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
90d0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74  OFF] is set, but
90e0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20   most .** VFSes 
90f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9100: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75   signal and shou
9110: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9120: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  re this opcode..
9130: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
9140: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9160: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9170: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20  is.** opcode as 
9180: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
9190: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
91a0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
91b0: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74  lized VFSes.** t
91c0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
91d0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
91e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
91f0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9200: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9210: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9220: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9230: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9240: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9250: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9260: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9270: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9280: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9290: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
92a0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
92b0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
92c0: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
92d0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
92e0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
92f0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9300: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9310: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9320: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9330: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9340: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9350: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9360: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9370: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9380: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9390: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
93a0: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
93b0: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
93c0: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
93d0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
93e0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
93f0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9400: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9410: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9420: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9430: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9440: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9450: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9460: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9470: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9480: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9490: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
94a0: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
94b0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
94c0: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
94d0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
94e0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
94f0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9500: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9510: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9520: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9530: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9540: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9550: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9560: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9570: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9580: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9590: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
95a0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
95b0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
95c0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
95d0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
95e0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
95f0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9600: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9610: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9620: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9630: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9640: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9660: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9670: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9680: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9690: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
96a0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
96b0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
96c0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
96d0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
96e0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
96f0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9700: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9710: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9720: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9730: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9740: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9750: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9770: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9780: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9790: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
97a0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
97b0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
97c0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
97d0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
97e0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
97f0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9800: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9810: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9820: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9830: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9840: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9850: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9860: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9870: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9880: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9890: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
98a0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
98b0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
98c0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
98d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
98e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
98f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9900: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9910: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9920: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9930: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9940: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9950: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9960: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9970: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9980: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9990: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
99a0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
99b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
99c0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
99d0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
99e0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
99f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9a00: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9a10: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9a20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9a30: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9a40: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9a50: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9a60: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9a70: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9a80: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9a90: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9aa0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9ab0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9ac0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9ad0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9ae0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9af0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9b00: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9b10: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9b20: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9b30: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b40: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9b50: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9b60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9b70: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9b80: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9b90: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
9ba0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
9bb0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
9bc0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
9bd0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9be0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9bf0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9c00: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9c10: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9c20: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
9c30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9c40: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
9c50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9c60: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
9c70: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
9c80: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
9c90: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
9ca0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
9cb0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
9cc0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
9cd0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
9ce0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
9cf0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
9d00: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
9d10: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
9d20: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
9d30: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
9d40: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
9d50: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
9d60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9d70: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9d80: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9d90: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9da0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
9db0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
9dc0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
9dd0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
9de0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
9df0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
9e00: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
9e10: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
9e20: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
9e30: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
9e40: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
9e50: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
9e60: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
9e70: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
9e80: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
9e90: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
9ea0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
9eb0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
9ec0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9ed0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
9ee0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
9ef0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
9f00: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
9f10: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
9f20: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
9f30: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
9f40: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
9f50: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
9f60: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
9f70: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
9f80: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
9f90: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
9fa0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
9fb0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
9fc0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
9fd0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9fe0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
9ff0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a000: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a010: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a020: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a030: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a040: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a050: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a060: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a070: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a080: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a090: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a0a0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a0b0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a0c0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a0d0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a0e0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a0f0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a100: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a110: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a120: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a130: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a140: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a150: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a160: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a170: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a180: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a190: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a1a0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a1b0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a1c0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a1d0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a1e0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a1f0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a200: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a210: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a220: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a230: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a240: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a250: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a260: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a270: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a280: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a290: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a2a0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a2b0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a2c0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a2d0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a2e0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a2f0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a300: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a310: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a320: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a330: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a340: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a350: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a370: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a380: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a390: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a3a0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a3b0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a3c0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a3d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a3e0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a3f0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a400: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a410: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a420: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a430: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a440: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a450: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a460: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a470: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a480: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a490: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a4a0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a4b0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a4c0: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a4d0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a4e0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a4f0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a500: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a510: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a520: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
a530: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
a540: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
a550: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
a560: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
a570: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
a580: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
a590: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a5a0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a5b0: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
a5c0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
a5d0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
a5e0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
a5f0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
a600: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
a610: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
a620: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
a630: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
a640: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
a650: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a660: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
a670: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
a680: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
a690: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
a6a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
a6b0: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
a6c0: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
a6d0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
a6e0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
a6f0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
a700: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
a710: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
a720: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
a730: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
a740: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
a750: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
a760: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
a770: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
a780: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
a790: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
a7a0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
a7b0: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
a7c0: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
a7d0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
a7e0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
a7f0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
a800: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
a810: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
a820: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
a830: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
a840: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
a850: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
a860: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
a870: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
a880: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
a890: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
a8a0: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
a8b0: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
a8c0: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
a8d0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
a8e0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
a8f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
a900: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
a910: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
a920: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
a930: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
a940: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
a950: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
a960: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
a970: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
a980: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
a990: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
a9a0: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
a9b0: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
a9c0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
a9d0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
a9e0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
a9f0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aa00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aa10: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aa20: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
aa30: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
aa40: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
aa50: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aa60: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
aa70: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
aa80: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
aa90: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
aaa0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
aab0: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
aac0: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
aad0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
aae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
aaf0: 50 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65  P_LIMIT]].** The
ab00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
ab10: 4d 41 50 5f 4c 49 4d 49 54 5d 20 66 69 6c 65 20  MAP_LIMIT] file 
ab20: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
ab30: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
ab40: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
ab50: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
ab60: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
ab70: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
ab80: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
ab90: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
aba0: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
abb0: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
abc0: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
abd0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
abe0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
abf0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
ac00: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
ac10: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
ac20: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ac30: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
ac40: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
ac50: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
ac60: 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 6c  ** the originall
ac70: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
ac80: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
ac90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
aca0: 69 74 20 63 61 6e 20 62 65 0a 2a 2a 20 71 75 65  it can be.** que
acb0: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
acc0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
acd0: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
ace0: 72 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  r.  This file-co
acf0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 75 73 65 64  ntrol.** is used
ad00: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
ad10: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
ad20: 20 6d 6d 61 70 5f 6c 69 6d 69 74 5d 2e 0a 2a 2a   mmap_limit]..**
ad30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
ad40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ad50: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
ad60: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
ad70: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
ad80: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ad90: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
ada0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
adb0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
adc0: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
add0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
ade0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
adf0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
ae00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
ae10: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
ae20: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
ae30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
ae40: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
ae50: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
ae60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
ae70: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
ae80: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
ae90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
aea0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
aeb0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
aec0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
aed0: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
aee0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
aef0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
af00: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
af10: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
af20: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
af30: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
af40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
af50: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
af60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
af70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
af80: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
af90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
afa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
afb0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
afc0: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
afd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
afe0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
aff0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
b000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b010: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
b020: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
b030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b040: 4c 5f 4d 4d 41 50 5f 4c 49 4d 49 54 20 20 20 20  L_MMAP_LIMIT    
b050: 20 20 20 20 20 20 20 20 20 31 38 0a 0a 2f 2a 0a           18../*.
b060: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
b070: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
b080: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
b090: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
b0a0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
b0b0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
b0c0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
b0d0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
b0e0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
b0f0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
b100: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
b110: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
b120: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
b130: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
b140: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
b150: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
b160: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
b170: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
b180: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
b190: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
b1a0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
b1b0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
b1c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
b1d0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
b1e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
b1f0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
b200: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
b210: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
b220: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
b230: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
b240: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
b250: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
b260: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
b270: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
b280: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
b290: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
b2a0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
b2b0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
b2c0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
b2d0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
b2e0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
b2f0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
b300: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
b310: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
b320: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
b330: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
b340: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
b350: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
b360: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
b370: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
b380: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
b390: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
b3a0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
b3b0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
b3c0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
b3d0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
b3e0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
b3f0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
b400: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
b410: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
b420: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
b430: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
b440: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
b450: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
b460: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
b470: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
b480: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
b490: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
b4a0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
b4b0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
b4c0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
b4d0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
b4e0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
b4f0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
b500: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
b510: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
b520: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
b530: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
b540: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
b550: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
b560: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
b570: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
b580: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
b590: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
b5a0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
b5b0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
b5c0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
b5d0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
b5e0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
b5f0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
b600: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
b610: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
b620: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
b630: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
b640: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
b650: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
b660: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
b670: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
b680: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
b690: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
b6a0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
b6b0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
b6c0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
b6d0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
b6e0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
b6f0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
b700: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
b710: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
b720: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
b730: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
b740: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
b750: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
b760: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
b770: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
b780: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
b790: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
b7a0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
b7b0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
b7c0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
b7d0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
b7e0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
b7f0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
b800: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
b810: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
b820: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
b830: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
b840: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
b850: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
b860: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
b870: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
b880: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
b890: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
b8a0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
b8b0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
b8c0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
b8d0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
b8e0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
b8f0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
b900: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
b910: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
b920: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
b930: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
b940: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
b950: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
b960: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
b970: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
b980: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
b990: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
b9a0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
b9b0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
b9c0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
b9d0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
b9e0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
b9f0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ba00: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ba10: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ba20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ba30: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ba40: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ba50: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ba60: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
ba70: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
ba80: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
ba90: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
baa0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
bab0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
bac0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
bad0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
bae0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
baf0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
bb00: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
bb10: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
bb20: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
bb30: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
bb40: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
bb50: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
bb60: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
bb70: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
bb80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
bb90: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
bba0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
bbb0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
bbc0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
bbd0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
bbe0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
bbf0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
bc00: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
bc10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
bc20: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
bc30: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
bc40: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
bc50: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
bc60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
bc70: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
bc80: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
bc90: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
bca0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
bcb0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
bcc0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
bcd0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
bce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
bcf0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
bd00: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
bd10: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
bd20: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
bd30: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
bd40: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
bd50: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
bd60: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
bd70: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
bd80: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
bd90: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
bda0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
bdb0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
bdc0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
bdd0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
bde0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
bdf0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
be00: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
be10: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
be20: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
be30: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
be40: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
be50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
be60: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
be70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
be80: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
be90: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bea0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
beb0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
bec0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
bed0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
bee0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
bef0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
bf00: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
bf10: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
bf20: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
bf30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
bf40: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
bf50: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
bf60: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
bf70: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
bf80: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
bf90: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
bfa0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
bfb0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
bfc0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
bfd0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
bfe0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
bff0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
c000: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
c010: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
c020: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c030: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
c040: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
c050: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
c060: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
c070: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
c080: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
c090: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
c0a0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
c0b0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
c0c0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
c0d0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
c0e0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
c0f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
c100: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
c110: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
c120: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c130: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
c140: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
c150: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
c160: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
c170: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c180: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
c190: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
c1a0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
c1b0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
c1c0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
c1d0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
c1e0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
c1f0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
c200: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
c210: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
c220: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
c230: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
c240: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
c250: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
c260: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
c270: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
c280: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
c290: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
c2a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
c2b0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
c2c0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
c2d0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
c2e0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
c2f0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
c300: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
c310: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
c320: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
c330: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
c340: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
c350: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
c360: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
c370: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
c380: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
c390: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
c3a0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
c3b0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
c3c0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
c3d0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
c3e0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
c3f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
c400: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
c410: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
c420: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
c430: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
c440: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
c450: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
c460: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
c470: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
c480: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
c490: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
c4a0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
c4b0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
c4c0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
c4d0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
c4e0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
c4f0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
c500: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
c510: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
c520: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
c530: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
c540: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
c550: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
c560: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
c570: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
c580: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
c590: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
c5a0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
c5b0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
c5c0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
c5d0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
c5e0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
c5f0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
c600: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
c610: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
c620: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
c630: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
c640: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
c650: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
c660: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
c670: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
c680: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
c690: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
c6a0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
c6b0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
c6c0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
c6d0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
c6e0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
c6f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
c700: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
c710: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
c720: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
c730: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
c740: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c750: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
c760: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
c770: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
c780: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
c790: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
c7a0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
c7b0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
c7c0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
c7d0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
c7e0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
c7f0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
c800: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
c810: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
c820: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
c830: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
c840: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
c850: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
c860: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
c870: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
c880: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
c890: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
c8a0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
c8b0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
c8c0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
c8d0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
c8e0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
c8f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
c900: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
c910: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
c920: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
c930: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
c940: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
c950: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
c960: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
c970: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
c980: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
c990: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
c9a0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
c9b0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
c9c0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
c9d0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
c9e0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
c9f0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
ca00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
ca10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
ca20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
ca30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
ca40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
ca50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
ca60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
ca70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
ca80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
ca90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
caa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
cab0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
cac0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
cad0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
cae0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
caf0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
cb00: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
cb10: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
cb20: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
cb30: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
cb40: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
cb50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
cb60: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
cb70: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
cb80: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
cb90: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
cba0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
cbb0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
cbc0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
cbd0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
cbe0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
cbf0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
cc00: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
cc10: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
cc20: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
cc30: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
cc40: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
cc50: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
cc60: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
cc70: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
cc80: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
cc90: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
cca0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
ccb0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
ccc0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
ccd0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
cce0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
ccf0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
cd00: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
cd10: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
cd20: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
cd30: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
cd40: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
cd50: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
cd60: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
cd70: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
cd80: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
cd90: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
cda0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
cdb0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
cdc0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
cdd0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
cde0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
cdf0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
ce00: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
ce10: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
ce20: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
ce30: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
ce40: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
ce50: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
ce60: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
ce70: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
ce80: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
ce90: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
cea0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
ceb0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
cec0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
ced0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
cee0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
cef0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
cf00: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
cf10: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
cf20: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
cf30: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
cf40: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
cf50: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
cf60: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
cf70: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
cf80: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
cf90: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
cfa0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
cfb0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
cfc0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
cfd0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
cfe0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
cff0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
d000: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
d010: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
d020: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
d030: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
d040: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
d050: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
d060: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
d070: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
d080: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
d090: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
d0a0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
d0b0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
d0c0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
d0d0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
d0e0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
d0f0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
d100: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
d110: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
d120: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
d130: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
d140: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
d150: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
d160: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
d170: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
d180: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
d190: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
d1a0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
d1b0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
d1c0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
d1d0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
d1e0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
d1f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d200: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
d210: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
d220: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
d230: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
d240: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
d250: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
d260: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
d270: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
d280: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
d290: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d2a0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
d2b0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
d2c0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
d2d0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
d2e0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
d2f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d300: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
d310: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
d320: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
d330: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d340: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
d350: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
d360: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
d370: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
d380: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d390: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d3a0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
d3b0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
d3c0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
d3d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
d3e0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
d3f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
d400: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
d410: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
d420: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
d430: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
d440: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
d450: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
d460: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
d470: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
d480: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
d490: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
d4a0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
d4b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d4c0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
d4d0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
d4e0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
d4f0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
d500: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
d510: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
d520: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
d530: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
d540: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
d550: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
d560: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
d570: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d580: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d590: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
d5a0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
d5b0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
d5c0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
d5d0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
d5e0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
d5f0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
d600: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d610: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
d620: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
d630: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
d640: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
d650: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
d660: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
d670: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
d680: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
d690: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
d6a0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
d6b0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
d6c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
d6d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
d6e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
d6f0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d700: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
d710: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
d720: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
d730: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
d740: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
d750: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
d760: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
d770: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
d780: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
d790: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
d7a0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
d7b0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
d7c0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
d7d0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
d7e0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
d7f0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
d800: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
d810: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
d820: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
d830: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
d840: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
d850: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
d860: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d870: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
d880: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
d890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
d8a0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
d8b0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
d8c0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
d8d0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
d8e0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
d8f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
d900: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
d910: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
d920: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
d930: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
d940: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
d950: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
d960: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
d970: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
d980: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
d990: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
d9a0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
d9b0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d9c0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d9d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
d9e0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
d9f0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
da00: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
da10: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
da20: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
da30: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
da40: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
da50: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
da60: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
da70: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
da80: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
da90: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
daa0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
dab0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
dac0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
dad0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
dae0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
daf0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
db00: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
db10: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
db20: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
db30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
db40: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
db50: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
db60: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
db70: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
db80: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
db90: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
dba0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
dbb0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
dbc0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
dbd0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
dbe0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
dbf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dc00: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
dc10: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
dc20: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
dc30: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
dc40: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
dc50: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
dc60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dc70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
dc80: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
dc90: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
dca0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
dcb0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
dcc0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
dcd0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
dce0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
dcf0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
dd00: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
dd10: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
dd20: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
dd30: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
dd40: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
dd50: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
dd60: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
dd70: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
dd80: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
dd90: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
dda0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
ddb0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ddc0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
ddd0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
dde0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
ddf0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
de00: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
de10: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
de20: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
de30: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
de40: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
de50: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
de60: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
de70: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
de80: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
de90: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
dea0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
deb0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
dec0: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
ded0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
dee0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
def0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
df00: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
df10: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
df20: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
df30: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
df40: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
df50: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
df60: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
df70: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
df80: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
df90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
dfa0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
dfb0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
dfc0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
dfd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
dfe0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
dff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e000: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
e010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e020: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
e030: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
e040: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e050: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
e060: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
e070: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
e080: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
e090: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
e0a0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
e0b0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
e0c0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
e0d0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
e0e0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
e0f0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
e100: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
e110: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
e120: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
e130: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
e140: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
e150: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
e160: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
e170: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e180: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
e190: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
e1a0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
e1b0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
e1c0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
e1d0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
e1e0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
e1f0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
e200: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
e210: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
e220: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
e230: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
e240: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
e250: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
e260: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
e270: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
e280: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
e290: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
e2a0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
e2b0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
e2c0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
e2d0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
e2e0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
e2f0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
e300: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
e310: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
e320: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
e330: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
e340: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e350: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
e360: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
e370: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
e380: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
e390: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
e3a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e3b0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
e3c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
e3d0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
e3e0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
e3f0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
e400: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
e410: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
e420: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
e430: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
e440: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
e450: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
e460: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
e470: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e480: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
e490: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
e4a0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
e4b0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
e4c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
e4d0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
e4e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e4f0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
e500: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
e510: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e520: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
e530: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
e540: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
e550: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
e560: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
e570: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
e580: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
e590: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e5a0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
e5b0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
e5c0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
e5d0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
e5e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
e5f0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
e600: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
e610: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
e620: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
e630: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
e640: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
e650: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
e660: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
e670: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
e680: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
e690: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
e6a0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
e6b0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
e6c0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
e6d0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
e6e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
e6f0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
e700: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
e710: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
e720: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
e730: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
e740: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
e750: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
e760: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e770: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
e780: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
e790: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
e7a0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
e7b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e7c0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
e7d0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
e7e0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
e7f0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
e800: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
e810: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
e820: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
e830: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
e840: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
e850: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
e860: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
e870: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
e880: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
e890: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
e8a0: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
e8b0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
e8c0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
e8d0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
e8e0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
e8f0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
e900: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e910: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
e920: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
e930: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
e940: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
e950: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
e960: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
e970: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
e980: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
e990: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
e9a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
e9b0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
e9c0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
e9d0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
e9e0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
e9f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
ea00: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
ea10: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
ea20: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
ea30: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
ea40: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
ea50: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
ea60: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
ea70: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
ea80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
ea90: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
eaa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
eab0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
eac0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
ead0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
eae0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
eaf0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
eb00: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
eb10: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
eb20: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
eb30: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
eb40: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
eb50: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
eb60: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
eb70: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
eb80: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
eb90: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
eba0: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
ebb0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
ebc0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
ebd0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
ebe0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
ebf0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
ec00: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
ec10: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
ec20: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
ec30: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
ec40: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
ec50: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
ec60: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ec70: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
ec80: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
ec90: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
eca0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
ecb0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
ecc0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
ecd0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
ece0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
ecf0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
ed00: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
ed10: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
ed20: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
ed30: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
ed40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
ed50: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
ed60: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
ed70: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
ed80: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
ed90: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
eda0: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
edb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
edc0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
edd0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
ede0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
edf0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
ee00: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
ee10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
ee20: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
ee30: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
ee40: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
ee50: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
ee60: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
ee70: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
ee80: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
ee90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
eea0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
eeb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
eec0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
eed0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
eee0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
eef0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
ef00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ef10: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
ef20: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
ef30: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
ef40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
ef50: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
ef60: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
ef70: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
ef80: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
ef90: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
efa0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
efb0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
efc0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
efd0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
efe0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
eff0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
f000: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
f010: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
f020: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
f030: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
f040: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
f050: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
f060: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
f070: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
f080: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
f090: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
f0a0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
f0b0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
f0c0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
f0d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f0e0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
f0f0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
f100: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
f110: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
f120: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
f130: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
f140: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
f150: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
f160: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
f170: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
f180: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f190: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
f1a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
f1b0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
f1c0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
f1d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
f1e0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
f1f0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
f200: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f210: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
f220: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
f230: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
f240: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
f250: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
f260: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
f270: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
f280: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
f290: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f2a0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
f2b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
f2c0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
f2d0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
f2e0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
f2f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
f300: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
f310: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
f320: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
f330: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
f340: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
f350: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
f360: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f370: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
f380: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
f390: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
f3a0: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
f3b0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
f3c0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
f3d0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
f3e0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
f3f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
f400: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
f410: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
f420: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f430: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
f440: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
f450: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
f460: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
f470: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f480: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
f490: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
f4a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f4b0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
f4c0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
f4d0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
f4e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f4f0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
f500: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f510: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
f520: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
f530: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
f540: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
f550: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f560: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
f570: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
f580: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f590: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
f5a0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
f5b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
f5c0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
f5d0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
f5e0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
f5f0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
f600: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f610: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
f620: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
f630: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
f640: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
f650: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
f660: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
f670: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
f680: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
f690: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
f6a0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f6b0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
f6c0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
f6d0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
f6e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f6f0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
f700: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
f710: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
f720: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
f730: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
f740: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
f750: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
f760: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
f770: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
f780: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
f790: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
f7a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f7b0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
f7c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
f7d0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f7e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
f7f0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
f800: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
f810: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
f820: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
f830: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
f840: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
f850: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
f860: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
f870: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
f880: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
f890: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
f8a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f8b0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
f8c0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f8d0: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
f8e0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f8f0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
f900: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
f910: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
f920: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
f930: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
f940: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
f950: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
f960: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
f970: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
f980: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f990: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
f9a0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
f9b0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
f9c0: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
f9d0: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
f9e0: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
f9f0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
fa00: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fa10: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
fa20: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
fa30: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
fa40: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
fa50: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
fa60: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
fa70: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
fa80: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
fa90: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
faa0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
fab0: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
fac0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
fad0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
fae0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
faf0: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
fb00: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
fb10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
fb20: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
fb30: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
fb40: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
fb50: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
fb60: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
fb70: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
fb80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
fb90: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
fba0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
fbb0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
fbc0: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
fbd0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
fbe0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
fbf0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
fc00: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
fc10: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
fc20: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
fc30: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
fc40: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
fc50: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
fc60: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
fc70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
fc80: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
fc90: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
fca0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
fcb0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
fcc0: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
fcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
fce0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
fcf0: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
fd00: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
fd10: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
fd20: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
fd30: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
fd40: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
fd50: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
fd60: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
fd70: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
fd80: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
fd90: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
fda0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
fdb0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
fdc0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
fdd0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
fde0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
fdf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
fe00: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
fe10: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
fe20: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
fe30: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
fe40: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
fe50: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
fe60: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fe70: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
fe80: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
fe90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
fea0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
feb0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
fec0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
fed0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
fee0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
fef0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
ff00: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
ff10: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
ff20: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
ff30: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
ff40: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
ff50: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
ff60: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
ff70: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
ff80: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
ff90: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
ffa0: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
ffb0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
ffc0: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
ffd0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
ffe0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
fff0: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
10000 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
10010 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
10020 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
10030 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
10040 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
10050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10060 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
10070 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
10080 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
10090 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
100a0 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
100b0 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
100c0 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
100d0 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
100e0 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
100f0 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
10100 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
10110 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
10120 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
10130 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
10140 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
10150 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
10160 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
10170 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
10180 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
10190 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
101a0 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
101b0 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
101c0 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
101d0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
101e0 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
101f0 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
10200 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
10210 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
10220 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
10230 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
10240 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
10250 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
10260 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
10270 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
10280 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
10290 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
102a0 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
102b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
102c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
102d0 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
102e0 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
102f0 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
10300 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10310 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
10320 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
10330 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
10340 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
10350 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
10360 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
10370 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
10380 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
10390 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
103a0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
103b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
103c0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
103d0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
103e0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
103f0 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
10400 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
10410 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
10420 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
10430 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
10440 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
10450 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
10460 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
10470 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
10480 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
10490 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
104a0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
104b0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
104c0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
104d0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
104e0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
104f0 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
10500 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10510 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
10520 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
10530 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
10540 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
10550 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
10560 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
10570 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
10580 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
10590 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
105a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
105b0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
105c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
105d0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
105e0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
105f0 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
10600 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
10610 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
10620 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
10630 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
10640 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10650 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
10660 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
10670 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
10680 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
10690 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
106a0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
106b0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
106c0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
106d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
106e0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
106f0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
10700 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
10710 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
10720 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
10730 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
10740 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10750 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
10760 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
10770 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10780 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
10790 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
107a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
107b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
107c0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
107d0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
107e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
107f0 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
10800 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
10810 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
10820 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
10830 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
10840 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
10850 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
10860 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
10870 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
10880 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
10890 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
108a0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
108b0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
108c0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
108d0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
108e0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
108f0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
10900 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
10910 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10920 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
10930 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
10940 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
10950 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
10960 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
10970 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
10980 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
10990 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
109a0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
109b0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
109c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
109d0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
109e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
109f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10a00 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
10a10 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
10a20 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
10a30 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
10a40 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
10a50 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
10a60 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
10a70 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
10a80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10a90 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
10aa0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
10ab0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
10ac0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
10ad0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
10ae0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
10af0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10b00 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
10b10 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
10b20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
10b30 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
10b40 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
10b50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
10b60 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
10b70 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
10b80 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
10b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10ba0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
10bb0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
10bc0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10bd0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
10be0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
10bf0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
10c00 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
10c10 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
10c20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
10c30 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10c40 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
10c50 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
10c60 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
10c70 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
10c80 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
10c90 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
10ca0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
10cb0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
10cc0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
10cd0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
10ce0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
10cf0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
10d00 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
10d10 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
10d20 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
10d30 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
10d40 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
10d50 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
10d60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10d70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10d80 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
10d90 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
10da0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
10db0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
10dc0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
10dd0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
10de0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
10df0 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
10e00 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
10e10 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
10e20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10e30 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
10e40 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
10e50 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
10e60 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
10e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
10e80 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
10e90 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
10ea0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10eb0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
10ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10ed0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
10ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
10ef0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
10f00 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
10f10 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
10f20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
10f30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
10f40 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
10f50 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
10f60 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
10f70 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
10f80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10f90 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
10fa0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
10fb0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
10fc0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
10fd0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
10fe0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
10ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11000 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
11010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
11020 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
11030 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
11040 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
11050 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
11060 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
11070 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
11080 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
11090 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
110a0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
110b0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
110c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
110d0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
110e0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
110f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11100 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11110 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11120 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11130 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11140 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11150 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
11160 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
11170 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
11180 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
11190 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
111a0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
111b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
111c0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
111d0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
111e0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
111f0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
11200 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11210 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11220 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
11230 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11240 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
11250 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11260 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11270 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11280 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11290 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
112a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
112b0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
112c0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
112d0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
112e0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
112f0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
11300 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
11310 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11320 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11340 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
11350 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
11360 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
11370 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
11380 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11390 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
113a0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
113b0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
113c0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
113d0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
113e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
113f0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
11400 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
11410 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
11420 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
11430 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
11440 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
11450 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
11460 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
11470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
11480 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
11490 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
114a0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
114b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
114c0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
114d0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
114e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
114f0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11500 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11510 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11520 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
11530 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
11540 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
11550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11560 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11570 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11580 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11590 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
115a0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
115b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
115c0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
115d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
115e0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
115f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11600 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11610 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11620 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11630 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11640 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11650 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11660 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11670 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
11680 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
11690 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
116a0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
116b0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
116c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
116d0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
116e0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
116f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11700 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
11710 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
11720 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
11730 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
11740 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
11750 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11760 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
11770 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
11780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
11790 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
117a0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
117b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
117c0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
117d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
117e0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
117f0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11800 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11810 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11820 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11830 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11840 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11850 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
11860 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
11870 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11880 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
11890 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
118a0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
118b0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
118c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
118d0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
118e0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
118f0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
11900 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
11910 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
11920 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
11930 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
11940 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
11950 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
11960 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
11970 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
11980 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
11990 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
119a0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
119b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
119c0 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
119d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
119e0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
119f0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
11a00 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
11a10 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
11a20 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
11a30 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
11a40 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
11a50 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
11a60 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
11a70 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
11a80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
11a90 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
11aa0 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
11ab0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
11ac0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
11ad0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
11ae0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
11af0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
11b00 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
11b10 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11b20 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
11b30 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
11b40 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
11b50 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
11b60 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11b70 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
11b80 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
11b90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
11ba0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
11bb0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
11bc0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
11bd0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
11be0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
11bf0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
11c00 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
11c10 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
11c20 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11c30 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
11c40 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
11c50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11c60 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
11c70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11c80 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
11c90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11ca0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
11cb0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
11cc0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
11cd0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
11ce0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
11cf0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11d00 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
11d10 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
11d20 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
11d30 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
11d40 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
11d50 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
11d60 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
11d70 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
11d80 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
11d90 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
11da0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
11db0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
11dc0 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
11dd0 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
11de0 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
11df0 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
11e00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11e10 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
11e20 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
11e30 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
11e40 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
11e50 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
11e60 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
11e70 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
11e80 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
11e90 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
11ea0 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
11eb0 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
11ec0 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
11ed0 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
11ee0 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
11ef0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
11f00 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
11f10 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
11f20 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
11f30 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
11f40 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
11f50 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
11f60 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
11f70 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
11f80 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
11f90 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
11fa0 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
11fb0 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
11fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
11fd0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
11fe0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
11ff0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
12000 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12010 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12020 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
12030 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12040 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
12050 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
12060 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12070 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
12080 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12090 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
120a0 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
120b0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
120c0 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
120d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
120e0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
120f0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
12100 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
12110 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12120 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
12130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
12140 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
12150 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12160 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
12170 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
12180 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
12190 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
121a0 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
121b0 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
121c0 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
121d0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
121e0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
121f0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
12200 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
12210 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
12220 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
12230 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
12240 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
12250 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
12260 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
12270 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
12280 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
12290 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
122a0 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
122b0 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
122c0 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
122d0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
122e0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
122f0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
12300 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
12310 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
12320 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
12330 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
12340 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
12350 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
12360 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
12370 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
12380 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12390 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
123a0 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
123b0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
123c0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
123d0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
123e0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
123f0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
12400 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
12410 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
12420 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
12430 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
12440 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
12450 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12460 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12470 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
12480 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
12490 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
124a0 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
124b0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
124c0 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
124d0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
124e0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
124f0 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
12500 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
12510 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
12520 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
12530 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
12540 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
12550 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12560 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
12570 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
12580 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
12590 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
125a0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
125b0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
125c0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
125d0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
125e0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
125f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12600 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
12610 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
12620 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
12630 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
12640 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12650 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
12660 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12670 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
12680 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
12690 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
126a0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
126b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
126c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
126d0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
126e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
126f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
12700 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12710 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
12720 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
12730 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
12740 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
12750 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
12760 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
12770 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
12780 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
12790 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
127a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
127b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
127c0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
127d0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
127e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
127f0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
12800 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
12810 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
12820 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
12830 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
12840 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
12850 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12860 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
12870 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
12880 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
12890 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
128a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
128b0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
128c0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
128d0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
128e0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
128f0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
12900 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
12910 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
12920 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
12930 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
12940 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
12950 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
12960 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
12970 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
12980 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
12990 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
129a0 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
129b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
129c0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
129d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
129e0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
129f0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12a00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12a10 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12a20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12a30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12a40 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
12a50 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12a60 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
12a70 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12a80 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12a90 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
12aa0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12ab0 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
12ac0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
12ad0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12ae0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
12af0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
12b00 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
12b10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
12b20 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12b30 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
12b40 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
12b50 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
12b60 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
12b70 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12b80 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12b90 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12ba0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12bb0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12bc0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12bd0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12be0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12bf0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12c00 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12c10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
12c20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12c30 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
12c40 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
12c50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12c60 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
12c70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
12c80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12ca0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
12cb0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
12cc0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
12cd0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12ce0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12cf0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12d00 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12d10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12d20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
12d30 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12d40 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
12d50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12d60 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12d70 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12d80 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12d90 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
12da0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12db0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12dc0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12dd0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
12de0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
12df0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
12e00 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
12e10 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
12e20 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
12e30 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
12e40 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
12e50 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
12e60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12e70 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12e80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12e90 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12ea0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12eb0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12ec0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
12ed0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
12ee0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
12ef0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
12f00 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
12f10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12f20 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
12f30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
12f40 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
12f50 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12f60 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12f70 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12f80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12f90 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
12fa0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12fb0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
12fc0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12fd0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
12fe0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
12ff0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
13000 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
13010 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
13020 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
13030 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
13040 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
13050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
13060 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13070 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
13080 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
13090 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
130a0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
130b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
130c0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
130d0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
130e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
130f0 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
13100 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
13110 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
13120 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
13130 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13140 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
13150 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
13160 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
13170 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
13180 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
13190 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
131a0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
131b0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
131c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
131d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
131e0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
131f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
13200 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13210 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13220 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13230 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13240 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
13250 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13260 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13270 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
13280 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
13290 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
132a0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
132b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
132c0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
132d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
132e0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
132f0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
13300 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13310 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
13320 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13330 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
13340 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13350 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
13360 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
13370 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13380 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13390 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
133a0 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
133b0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
133c0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
133d0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
133e0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
133f0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13400 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
13410 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
13420 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13430 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
13440 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
13450 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
13460 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13470 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
13480 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
13490 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
134a0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
134b0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
134c0 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
134d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
134e0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
134f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
13500 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
13510 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
13520 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
13530 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
13540 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
13550 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
13560 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
13570 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
13580 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
13590 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
135a0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
135b0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
135c0 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
135d0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
135e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
135f0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
13600 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
13610 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
13620 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13630 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
13640 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
13650 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
13660 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
13670 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
13680 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
13690 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
136a0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
136b0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
136c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
136d0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
136e0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
136f0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
13700 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
13710 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
13720 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
13730 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
13740 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
13750 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
13760 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
13770 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
13780 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
13790 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
137a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
137b0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
137c0 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
137d0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
137e0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
137f0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
13800 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
13810 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
13820 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
13830 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
13840 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
13850 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
13860 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13870 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13880 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
13890 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
138a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
138b0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
138c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
138d0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
138e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
138f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13900 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
13910 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
13920 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
13930 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
13940 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
13950 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
13960 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
13970 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
13980 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
13990 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
139a0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
139b0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
139c0 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
139d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
139e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
139f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
13a00 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
13a10 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
13a20 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
13a30 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
13a40 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
13a50 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
13a60 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
13a70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
13a80 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
13a90 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
13aa0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
13ab0 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
13ac0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
13ad0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
13ae0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
13af0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
13b00 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
13b10 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
13b20 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
13b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b40 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
13b50 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
13b60 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
13b70 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
13b80 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
13b90 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
13ba0 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
13bb0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
13bc0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
13bd0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
13be0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13bf0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
13c00 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
13c10 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
13c20 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
13c30 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
13c40 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
13c50 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20  nteger argument 
13c60 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
13c70 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f  eted as.** a boo
13c80 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
13c90 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
13ca0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
13cb0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
13cc0 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65  or.** full table
13cd0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
13ce0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20  ery optimizer.  
13cf0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
13d00 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
13d10 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
13d20 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
13d30 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
13d40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13d50 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
13d60 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
13d70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
13d80 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
13d90 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
13da0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
13db0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
13dc0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
13dd0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
13de0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
13df0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
13e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
13e10 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
13e20 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77  ** malfunction w
13e30 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
13e40 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
13e50 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
13e60 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
13e70 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
13e80 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
13e90 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
13ea0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
13eb0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
13ec0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
13ed0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
13ee0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
13ef0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13f00 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
13f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13f20 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
13f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13f40 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
13f50 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13f60 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
13f70 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
13f80 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
13f90 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
13fa0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
13fb0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
13fc0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
13fd0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
13fe0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
13ff0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dl>.**.** [[SQ
14000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14010 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14020 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14030 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14040 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14050 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14060 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14070 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45   the.** SQLITE_E
14080 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65  NABLE_SQLLOG pre
14090 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
140a0 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
140b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
140c0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
140d0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
140e0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
140f0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
14100 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
14110 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
14120 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
14130 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
14140 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
14150 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
14160 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
14170 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
14180 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
14190 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
141a0 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
141b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
141c0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
141d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
141e0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
141f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14200 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
14210 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
14220 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
14230 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
14240 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
14250 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
14260 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
14270 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
14280 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
14290 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
142a0 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
142b0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
142c0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
142d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
142e0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
142f0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
14300 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
14310 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14320 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
14330 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
14340 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
14350 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14360 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
14370 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
14380 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
14390 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
143a0 63 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  case..**.** [[SQ
143b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
143c0 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 3c 64 74 3e  _LIMIT]].** <dt>
143d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
143e0 41 50 5f 4c 49 4d 49 54 0a 2a 2a 20 3c 64 64 3e  AP_LIMIT.** <dd>
143f0 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
14400 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 36 34  t should be a 64
14410 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 61 6e  -bit integer (an
14420 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20   sqlite3_int64) 
14430 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 64  that.** is the d
14440 65 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 6e  efault maximum n
14450 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
14460 66 20 70 72 6f 63 65 73 73 20 61 64 64 72 65 73  f process addres
14470 73 20 73 70 61 63 65 20 74 68 61 74 0a 2a 2a 20  s space that.** 
14480 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20 66  should be used f
14490 6f 72 20 61 63 63 65 73 73 69 6e 67 20 65 61 63  or accessing eac
144a0 68 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  h database file 
144b0 75 73 69 6e 67 20 6d 65 6d 6f 72 79 20 6d 61 70  using memory map
144c0 70 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 64 65 66  ping..** The def
144d0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
144e0 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
144f0 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
14500 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
14510 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
14520 50 52 41 47 4d 41 20 6d 6d 61 70 5f 6c 69 6d 69  PRAGMA mmap_limi
14530 74 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  t] command, or b
14540 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
14550 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
14560 50 5f 4c 49 4d 49 54 5d 20 66 69 6c 65 20 63 6f  P_LIMIT] file co
14570 6e 74 72 6f 6c 2e 20 20 54 68 65 20 76 61 6c 75  ntrol.  The valu
14580 65 20 73 65 74 20 68 65 72 65 20 6f 76 65 72 72  e set here overr
14590 69 64 65 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ides the.** comp
145a0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
145b0 20 74 68 61 74 20 69 73 20 73 65 74 20 75 73 69   that is set usi
145c0 6e 67 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  ng [SQLITE_DEFAU
145d0 4c 54 5f 4d 4d 41 50 5f 4c 49 4d 49 54 5d 2e 0a  LT_MMAP_LIMIT]..
145e0 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  ** If the argume
145f0 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  nt to this optio
14600 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  n is negative, t
14610 68 65 6e 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  hen.** the memor
14620 79 20 6d 61 70 20 6c 69 6d 69 74 20 69 73 20 73  y map limit is s
14630 65 74 20 74 6f 20 74 68 65 20 63 6f 6d 70 69 6c  et to the compil
14640 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
14650 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
14660 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14670 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
14680 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
14690 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
146a0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
146b0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
146c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
146d0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
146e0 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
146f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14700 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
14710 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
14720 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
14730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14740 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
14750 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
14760 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
14770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14780 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14790 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
147a0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
147b0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
147c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
147d0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
147e0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
147f0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14810 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
14820 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
14830 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
14840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14850 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
14860 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
14870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14880 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
14890 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
148a0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
148b0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
148c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
148d0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
148e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
148f0 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
14900 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
14910 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
14920 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
14930 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
14940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14950 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
14960 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
14970 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14980 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
14990 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
149a0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
149b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
149c0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
149d0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
149e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
149f0 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
14a00 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
14a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14a20 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
14a30 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
14a40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14a50 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14a60 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
14a70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14a80 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
14a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14aa0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
14ab0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
14ac0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
14ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14ae0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14af0 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
14b00 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14b20 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
14b30 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
14b40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 4c  TE_CONFIG_MMAP_L
14b60 49 4d 49 54 20 20 20 32 32 20 20 2f 2a 20 73 71  IMIT   22  /* sq
14b70 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a  lite3_int64 */..
14b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14b90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
14ba0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
14bb0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
14bc0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
14bd0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
14be0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
14bf0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
14c00 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
14c10 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
14c20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
14c30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
14c40 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
14c50 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
14c60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14c70 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
14c80 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
14c90 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
14ca0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
14cb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14cc0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
14cd0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
14ce0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
14cf0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
14d00 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
14d10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14d20 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
14d30 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
14d40 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
14d50 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14d60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
14d70 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
14d80 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
14d90 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
14da0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
14db0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
14dc0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
14dd0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
14de0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
14df0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
14e00 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
14e10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
14e20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
14e30 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
14e40 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
14e50 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
14e60 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
14e70 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
14e80 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
14e90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14ea0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
14eb0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
14ec0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
14ed0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
14ee0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
14ef0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
14f00 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
14f10 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
14f20 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
14f30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
14f40 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
14f50 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
14f60 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
14f70 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
14f80 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
14f90 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
14fa0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
14fb0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
14fc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14fd0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
14fe0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
14ff0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
15000 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
15010 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
15020 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15030 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
15040 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
15050 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
15060 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
15070 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
15080 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
15090 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
150a0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
150b0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
150c0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
150d0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
150e0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
150f0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
15100 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15110 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
15120 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15130 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
15140 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
15150 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
15160 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
15170 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
15180 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
15190 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
151a0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
151b0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
151c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
151d0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
151e0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
151f0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
15200 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
15210 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
15220 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
15230 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
15240 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
15250 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
15260 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
15270 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15290 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
152a0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
152b0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
152c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
152d0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
152e0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
152f0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
15300 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
15310 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
15320 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
15330 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
15340 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
15350 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
15360 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
15370 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
15380 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
15390 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
153a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
153b0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
153c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
153d0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
153e0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
153f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15400 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
15410 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
15420 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
15430 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
15440 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
15450 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
15460 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
15470 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
15480 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
15490 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
154a0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
154b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
154c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
154d0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
154e0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
154f0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
15500 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
15510 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
15520 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
15530 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
15540 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
15550 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
15560 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
15570 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
15580 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
15590 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
155a0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
155b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
155c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
155d0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
155e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
155f0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
15600 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
15610 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
15620 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
15630 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
15640 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
15650 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
15660 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15670 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
15680 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
15690 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
156a0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
156b0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
156c0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
156d0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
156e0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
156f0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
15700 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
15710 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
15720 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
15730 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
15740 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
15750 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
15760 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
15770 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
15780 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
15790 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
157a0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
157b0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
157c0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
157d0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
157e0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
157f0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
15800 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
15810 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
15820 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
15830 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
15840 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
15850 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
15860 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
15870 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
15880 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
15890 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
158a0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
158b0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
158c0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
158d0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
158e0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
158f0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
15900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
15910 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
15920 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
15930 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
15940 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
15950 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
15960 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
15970 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
15980 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
15990 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
159a0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
159b0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
159c0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
159d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
159e0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
159f0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
15a00 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
15a10 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
15a20 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
15a30 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
15a40 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
15a50 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
15a60 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
15a70 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
15a80 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
15a90 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
15aa0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
15ab0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
15ac0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
15ad0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
15ae0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
15af0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
15b00 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
15b10 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
15b20 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
15b30 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
15b40 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
15b50 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
15b60 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
15b70 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
15b80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
15b90 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
15ba0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
15bb0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
15bc0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
15bd0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
15be0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
15bf0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
15c00 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
15c10 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
15c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
15c30 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15c40 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20  gument.  ^As of 
15c50 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
15c60 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69  .7.7, this routi
15c70 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74  nes.** records t
15c80 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
15c90 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64  owid of both ord
15ca0 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64  inary tables and
15cb0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
15cc0 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  ]..** ^If no suc
15cd0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
15ce0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
15cf0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
15d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15d10 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
15d20 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
15d30 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
15d40 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
15d50 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
15d60 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
15d70 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
15d80 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
15d90 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
15da0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
15db0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
15dc0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
15dd0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
15de0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
15df0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
15e00 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
15e10 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
15e20 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
15e30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
15e40 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
15e50 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
15e60 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
15e70 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
15e80 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
15e90 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
15ea0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
15eb0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
15ec0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
15ed0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
15ee0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
15ef0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
15f00 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
15f10 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
15f20 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
15f30 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
15f40 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
15f50 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
15f60 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
15f70 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
15f80 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
15f90 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
15fa0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
15fb0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
15fc0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
15fd0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
15fe0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
15ff0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
16000 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
16010 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
16020 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
16030 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
16040 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
16050 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
16060 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
16070 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
16080 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
16090 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
160a0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
160b0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
160c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
160d0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
160e0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
160f0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
16100 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
16110 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
16120 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
16130 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
16140 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
16150 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
16160 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
16170 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
16180 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
16190 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
161a0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
161b0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
161c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
161d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
161e0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
161f0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
16200 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
16210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
16220 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
16230 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16240 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
16250 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
16260 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
16270 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
16280 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
16290 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
162a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
162b0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
162c0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
162d0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
162e0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
162f0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
16300 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
16310 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
16320 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
16330 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
16340 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
16350 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16360 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
16370 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
16380 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
16390 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
163a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
163b0 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
163c0 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
163d0 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
163e0 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
163f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
16400 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
16410 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
16420 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
16430 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
16440 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
16450 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
16460 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
16470 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
16480 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
16490 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
164a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
164b0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
164c0 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
164d0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
164e0 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
164f0 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
16500 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
16510 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
16520 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
16530 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
16540 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
16550 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
16560 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
16570 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
16580 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
16590 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
165a0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
165b0 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
165c0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
165d0 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
165e0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
165f0 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
16600 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
16610 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
16620 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
16630 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
16640 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
16650 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
16660 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
16670 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
16680 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
16690 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
166a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
166b0 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
166c0 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
166d0 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
166e0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
166f0 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
16700 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
16710 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
16720 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
16730 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
16740 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
16750 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
16760 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
16770 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
16780 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
16790 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
167a0 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
167b0 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
167c0 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
167d0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
167e0 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
167f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
16800 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
16810 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
16820 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
16830 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
16840 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
16850 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
16860 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
16870 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
16880 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
16890 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
168a0 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
168b0 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
168c0 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
168d0 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
168e0 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
168f0 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
16900 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
16910 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
16920 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16930 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
16940 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
16950 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
16960 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
16970 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
16980 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16990 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
169a0 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
169b0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
169c0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
169d0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
169e0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
169f0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
16a00 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
16a10 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
16a20 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
16a30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
16a40 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
16a50 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
16a60 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
16a70 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
16a80 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
16a90 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
16aa0 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
16ab0 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
16ac0 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
16ad0 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
16ae0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
16af0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
16b00 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
16b10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
16b20 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
16b30 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
16b40 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
16b50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
16b60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
16b70 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
16b80 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
16b90 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
16ba0 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
16bb0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
16bc0 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
16bd0 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
16be0 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
16bf0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
16c00 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
16c10 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
16c20 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16c30 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
16c40 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
16c50 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
16c60 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
16c70 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
16c80 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
16c90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
16ca0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
16cb0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
16cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
16cd0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
16ce0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
16cf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
16d00 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
16d10 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
16d20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
16d30 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
16d40 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
16d50 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
16d60 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
16d70 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
16d80 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
16d90 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16da0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16db0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
16dc0 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
16dd0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
16de0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
16df0 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
16e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16e10 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
16e20 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
16e30 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
16e40 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
16e50 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
16e60 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
16e70 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
16e80 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
16e90 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
16ea0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
16eb0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
16ec0 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
16ed0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
16ee0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
16ef0 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
16f00 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
16f10 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
16f20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
16f30 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
16f40 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
16f50 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
16f60 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
16f70 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
16f80 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
16f90 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
16fa0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
16fb0 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
16fc0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
16fd0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
16fe0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
16ff0 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
17000 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
17010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
17020 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
17030 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
17040 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
17050 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
17060 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
17070 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
17080 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
17090 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
170a0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
170b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
170c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
170d0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
170e0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
170f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
17100 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
17110 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
17120 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
17130 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
17140 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17150 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17160 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
17170 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
17180 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
17190 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
171a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
171b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
171c0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
171d0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
171e0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
171f0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
17200 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
17210 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
17220 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
17230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17240 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
17250 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
17260 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17270 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
17280 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
17290 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
172a0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
172b0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
172c0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
172d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
172e0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
172f0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
17300 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
17310 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
17320 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
17330 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
17340 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
17350 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
17360 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
17370 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
17380 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
17390 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
173a0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
173b0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
173c0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
173d0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
173e0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
173f0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
17400 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
17410 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
17420 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
17430 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
17440 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
17450 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
17460 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
17470 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17480 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
17490 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
174a0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
174b0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
174c0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
174d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
174e0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
174f0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
17500 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
17510 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
17520 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
17530 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
17540 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
17550 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
17560 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
17570 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
17580 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
17590 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
175a0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
175b0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
175c0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
175d0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
175e0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
175f0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
17600 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
17610 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
17620 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
17630 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
17640 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
17650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17660 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
17670 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
17680 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
17690 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
176a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
176b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
176c0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
176d0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
176e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
176f0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
17700 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
17710 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
17720 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
17730 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
17740 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
17750 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
17760 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
17770 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
17780 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
17790 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
177a0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
177b0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
177c0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
177d0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
177e0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
177f0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
17800 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
17810 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
17820 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17830 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
17840 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
17850 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
17860 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
17870 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
17880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17890 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
178a0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
178b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
178c0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
178d0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
178e0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
178f0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
17900 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
17910 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17920 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
17930 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17940 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
17950 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
17960 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
17970 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
17980 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
17990 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
179a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
179b0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
179c0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
179d0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
179e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
179f0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
17a00 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
17a10 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
17a20 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
17a30 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
17a40 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
17a50 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
17a60 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
17a70 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
17a80 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
17a90 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
17aa0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
17ab0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
17ac0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
17ad0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
17ae0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
17af0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
17b00 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
17b10 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
17b20 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
17b30 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
17b40 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
17b50 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
17b60 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
17b70 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
17b80 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
17b90 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
17ba0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
17bb0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
17bc0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
17bd0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
17be0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
17bf0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
17c00 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
17c10 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
17c20 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
17c30 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
17c40 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
17c50 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
17c60 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
17c70 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
17c80 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
17c90 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
17ca0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
17cb0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
17cc0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
17cd0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
17ce0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
17cf0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
17d00 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
17d10 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
17d20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17d30 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
17d40 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
17d50 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
17d60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
17d70 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
17d80 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
17d90 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
17da0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
17db0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
17dc0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
17dd0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
17de0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
17df0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
17e00 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
17e10 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
17e20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
17e30 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
17e40 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
17e50 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
17e60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
17e70 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
17e80 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
17e90 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
17ea0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
17eb0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
17ec0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
17ed0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
17ee0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
17ef0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
17f00 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
17f10 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
17f20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
17f30 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
17f40 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
17f50 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
17f60 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
17f70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
17f80 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
17f90 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
17fa0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
17fb0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
17fc0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
17fd0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
17fe0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
17ff0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
18000 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
18010 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18020 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
18030 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
18040 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
18050 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
18060 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
18070 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
18080 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
18090 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
180a0 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
180b0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
180c0 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
180d0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
180e0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
180f0 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
18100 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
18110 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
18120 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
18130 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
18140 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
18150 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
18160 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
18170 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
18180 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
18190 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
181a0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
181b0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
181c0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
181d0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
181e0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
181f0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
18200 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
18210 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18220 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
18230 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
18240 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
18250 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
18260 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
18270 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
18280 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
18290 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
182a0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
182b0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
182c0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
182d0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
182e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
182f0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
18300 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
18310 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
18320 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
18330 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18340 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
18350 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
18360 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
18370 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
18380 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
18390 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
183a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
183b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
183c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
183d0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
183e0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
183f0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
18400 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
18410 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
18420 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
18430 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
18440 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
18450 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
18460 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
18470 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
18480 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
18490 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
184a0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
184b0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
184c0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
184d0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
184e0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
184f0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
18500 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
18510 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
18520 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
18530 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18540 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
18550 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
18560 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
18570 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
18580 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
18590 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
185a0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
185b0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
185c0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
185d0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
185e0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
185f0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
18600 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
18610 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
18620 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
18630 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
18640 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
18650 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
18660 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
18670 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
18680 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
18690 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
186a0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
186b0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
186c0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
186d0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
186e0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
186f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
18700 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
18710 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
18720 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
18730 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
18740 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
18750 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
18760 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
18770 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
18780 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
18790 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
187a0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
187b0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
187c0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
187d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
187e0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
187f0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
18800 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
18810 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
18820 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
18830 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
18840 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
18850 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
18860 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
18870 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
18880 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
18890 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
188a0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
188b0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
188c0 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
188d0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
188e0 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
188f0 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
18900 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
18910 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
18920 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
18930 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
18940 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
18950 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
18960 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
18970 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
18980 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
18990 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
189a0 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
189b0 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
189c0 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
189d0 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
189e0 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
189f0 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
18a00 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
18a10 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
18a20 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
18a30 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
18a40 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
18a50 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
18a60 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
18a70 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
18a80 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
18a90 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
18aa0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
18ab0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
18ac0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
18ad0 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
18ae0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
18af0 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
18b00 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
18b10 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
18b20 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
18b30 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
18b40 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
18b50 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
18b60 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
18b70 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
18b80 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
18b90 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
18ba0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
18bb0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
18bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18bd0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
18be0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
18bf0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
18c00 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
18c10 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
18c20 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
18c30 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
18c40 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
18c50 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
18c60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
18c70 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
18c80 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
18c90 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
18ca0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
18cb0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
18cc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
18cd0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
18ce0 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
18cf0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
18d00 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
18d10 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
18d20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
18d30 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
18d40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
18d50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
18d60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
18d70 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
18d80 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
18d90 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
18da0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18db0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
18dc0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
18dd0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
18de0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
18df0 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
18e00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
18e10 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
18e20 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
18e30 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
18e40 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
18e50 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
18e60 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
18e70 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
18e80 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
18e90 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
18ea0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
18eb0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
18ec0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
18ed0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
18ee0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
18ef0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
18f00 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
18f10 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
18f20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
18f30 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
18f40 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
18f50 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
18f60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
18f70 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
18f80 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
18f90 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
18fa0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
18fb0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
18fc0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
18fd0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
18fe0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
18ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19000 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19010 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19020 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
19030 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19040 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
19050 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
19060 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
19070 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
19080 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
19090 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
190a0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
190b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
190c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
190d0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
190e0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
190f0 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
19100 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
19110 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
19120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19130 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
19140 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
19150 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a  ning Queries.**.
19160 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
19170 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
19180 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
19190 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
191a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
191b0 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
191c0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
191d0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
191e0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
191f0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
19200 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
19210 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
19220 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
19230 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
19240 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
19250 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
19260 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
19270 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
19280 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
19290 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
192a0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
192b0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
192c0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
192d0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
192e0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
192f0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
19300 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
19310 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
19320 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
19330 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
19340 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
19350 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
19360 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
19370 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
19380 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
19390 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
193a0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
193b0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
193c0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
193d0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
193e0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
193f0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
19400 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
19410 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
19420 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
19430 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
19440 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
19450 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
19460 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
19470 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
19480 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
19490 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
194a0 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
194b0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
194c0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
194d0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
194e0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
194f0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
19500 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
19510 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
19520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
19530 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
19540 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
19550 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
19560 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
19570 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
19580 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
19590 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
195a0 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
195b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
195c0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
195d0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
195e0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
195f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
19600 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
19610 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
19620 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
19630 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
19640 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
19650 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
19660 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
19670 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
19680 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
19690 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
196a0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
196b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
196c0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
196d0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
196e0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
196f0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
19700 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
19710 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19720 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
19730 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
19740 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
19750 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
19760 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
19770 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
19780 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
19790 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
197a0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
197b0 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
197c0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
197d0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
197e0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
197f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19800 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
19810 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
19820 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
19830 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
19840 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
19850 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19860 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
19870 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19880 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
19890 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
198a0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
198b0 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
198c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
198d0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
198e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
198f0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
19900 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19910 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
19920 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
19930 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
19940 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
19950 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
19960 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
19970 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
19980 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
19990 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
199a0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
199b0 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
199c0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
199d0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
199e0 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
199f0 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
19a00 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
19a10 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
19a20 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
19a30 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
19a40 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
19a50 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
19a60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
19a70 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
19a80 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
19a90 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
19aa0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
19ab0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
19ac0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
19ad0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
19ae0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
19af0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
19b00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
19b10 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
19b20 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
19b30 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
19b40 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
19b50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
19b60 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
19b70 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
19b80 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
19b90 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
19ba0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
19bb0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
19bc0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
19bd0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
19be0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19bf0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
19c00 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
19c10 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
19c20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
19c30 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
19c40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
19c50 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
19c60 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
19c70 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
19c80 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
19c90 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
19ca0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
19cb0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
19cc0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
19cd0 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
19ce0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
19cf0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
19d00 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
19d10 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
19d20 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
19d30 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
19d40 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
19d50 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
19d60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
19d70 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
19d80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
19d90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
19da0 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
19db0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
19dc0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
19dd0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
19de0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
19df0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
19e00 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
19e10 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
19e20 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
19e30 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
19e40 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
19e50 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
19e60 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
19e70 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
19e80 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
19e90 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
19ea0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
19eb0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
19ec0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
19ed0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
19ee0 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
19ef0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
19f00 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
19f10 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
19f20 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
19f30 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
19f40 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
19f50 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
19f60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19f70 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
19f80 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
19f90 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
19fa0 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
19fb0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
19fc0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
19fd0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
19fe0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
19ff0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1a000 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1a010 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1a020 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1a030 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1a040 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1a050 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1a060 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1a070 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1a080 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1a090 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1a0a0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1a0b0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1a0c0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1a0d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a0e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1a0f0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1a100 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1a110 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1a120 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1a130 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1a140 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1a150 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1a160 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1a170 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1a180 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1a190 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1a1a0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1a1b0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1a1c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a1d0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1a1e0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1a1f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1a200 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1a210 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1a220 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1a230 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1a240 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1a250 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1a260 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1a270 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1a280 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1a290 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1a2a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1a2b0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1a2c0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1a2d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1a2e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1a2f0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1a300 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1a310 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1a320 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1a330 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1a340 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1a350 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1a360 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1a370 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1a380 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1a390 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1a3a0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1a3b0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1a3c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1a3d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1a3e0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1a3f0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1a400 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1a410 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1a420 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1a430 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1a440 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1a450 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1a460 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1a470 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1a480 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1a490 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1a4a0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1a4b0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1a4c0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1a4d0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1a4e0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1a4f0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1a500 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1a510 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1a520 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1a530 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1a540 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1a550 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1a560 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1a570 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1a580 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1a590 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1a5a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1a5b0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1a5c0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1a5d0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1a5e0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1a5f0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1a600 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1a610 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1a620 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1a630 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1a640 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1a650 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1a660 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1a670 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1a680 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1a690 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1a6a0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1a6b0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1a6c0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1a6d0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1a6e0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1a6f0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1a700 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1a710 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1a720 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1a730 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1a740 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1a750 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1a760 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1a770 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1a780 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1a790 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1a7a0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1a7b0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1a7c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1a7d0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1a7e0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1a7f0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1a800 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1a810 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a820 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a830 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1a840 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1a850 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1a860 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1a870 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1a880 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1a890 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1a8a0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1a8b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a8c0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1a8d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1a8e0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1a8f0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1a900 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1a910 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1a920 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1a930 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1a940 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1a950 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a960 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1a970 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1a980 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1a990 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1a9a0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1a9b0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1a9c0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1a9d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1a9e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1a9f0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1aa00 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1aa10 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1aa20 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1aa30 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1aa40 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1aa50 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1aa60 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1aa70 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1aa80 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1aa90 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1aaa0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1aab0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1aac0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1aad0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1aae0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1aaf0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ab00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1ab10 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1ab20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1ab30 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1ab40 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1ab50 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1ab60 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1ab70 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1ab80 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1ab90 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1aba0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1abb0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1abc0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1abd0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1abe0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1abf0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1ac00 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1ac10 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1ac20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1ac30 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1ac40 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1ac50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1ac60 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1ac70 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1ac80 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1ac90 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1aca0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1acb0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1acc0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1acd0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1ace0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1acf0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1ad00 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1ad10 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1ad20 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1ad30 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1ad40 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1ad50 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1ad60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ad70 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1ad80 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1ad90 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1ada0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1adb0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1adc0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1add0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1ade0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1adf0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1ae00 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1ae10 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1ae20 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1ae30 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1ae40 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1ae50 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1ae60 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1ae70 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1ae80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1ae90 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1aea0 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1aeb0 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
1aec0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1aed0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
1aee0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1aef0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1af00 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
1af10 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1af20 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1af30 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
1af40 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1af50 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1af60 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1af70 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1af80 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1af90 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1afa0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1afb0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1afc0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1afd0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1afe0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1aff0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b000 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1b010 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1b020 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1b030 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1b040 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1b050 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1b060 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1b070 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1b080 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1b090 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1b0a0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1b0b0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1b0c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b0d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b0e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1b0f0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1b100 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1b110 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1b120 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1b130 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1b140 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b150 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1b160 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1b170 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1b180 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1b190 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1b1a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1b1b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1b1c0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1b1d0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1b1e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b1f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1b200 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1b210 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1b220 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1b230 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1b240 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1b250 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1b260 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1b270 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1b280 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1b290 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1b2a0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1b2b0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1b2c0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1b2d0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1b2e0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1b2f0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1b300 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1b310 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1b320 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1b330 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1b340 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1b350 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1b360 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1b370 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1b380 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1b390 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1b3a0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1b3b0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1b3c0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1b3d0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1b3e0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1b3f0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1b400 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1b410 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1b420 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1b430 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1b440 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1b450 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1b460 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1b470 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1b480 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b490 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1b4a0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
1b4b0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1b4c0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
1b4d0 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1b4e0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1b4f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1b500 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1b510 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
1b520 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
1b530 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1b540 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b550 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1b560 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1b570 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1b580 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1b590 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b5a0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1b5b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1b5c0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1b5d0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1b5e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1b5f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1b600 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1b610 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1b620 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b630 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1b640 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1b650 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1b660 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1b670 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1b680 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1b690 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1b6a0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1b6b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1b6c0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1b6d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1b6e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1b6f0 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1b700 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1b710 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1b720 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1b730 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1b740 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1b750 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1b760 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1b770 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1b780 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1b790 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1b7a0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1b7b0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1b7c0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1b7d0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1b7e0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1b7f0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1b800 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1b810 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1b820 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1b830 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1b840 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1b850 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b860 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1b870 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1b880 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1b890 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1b8a0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1b8b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1b8c0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1b8d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1b8e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1b8f0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1b900 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1b910 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1b920 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1b930 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1b940 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1b950 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1b960 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1b970 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1b980 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1b990 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1b9a0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1b9b0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1b9c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1b9d0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1b9e0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1b9f0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1ba00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1ba10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1ba20 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1ba30 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1ba40 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1ba50 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1ba60 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1ba70 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1ba80 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1ba90 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1baa0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1bab0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1bac0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1bad0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1bae0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1baf0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1bb00 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1bb10 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1bb20 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1bb30 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1bb40 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1bb50 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1bb60 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1bb70 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1bb80 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1bb90 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1bba0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1bbb0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1bbc0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1bbd0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1bbe0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1bbf0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1bc00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1bc10 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1bc20 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1bc30 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1bc40 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1bc50 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1bc60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1bc70 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1bc80 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1bc90 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1bca0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1bcb0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1bcc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1bcd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1bce0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1bcf0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1bd00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1bd10 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1bd20 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1bd30 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1bd40 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1bd50 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1bd60 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1bd70 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1bd80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1bd90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1bda0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1bdb0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1bdc0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1bdd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1bde0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1bdf0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1be00 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1be10 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1be20 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1be30 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1be40 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1be50 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1be60 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1be70 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1be80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1be90 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1bea0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1beb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1bec0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1bed0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1bee0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1bef0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1bf00 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1bf10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1bf20 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1bf30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1bf40 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1bf50 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1bf60 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1bf70 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1bf80 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1bf90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1bfa0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1bfb0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1bfc0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1bfd0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1bfe0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1bff0 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1c000 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1c010 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1c020 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1c030 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1c040 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1c050 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c060 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1c070 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1c080 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1c090 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1c0a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1c0b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c0c0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1c0d0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1c0e0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1c0f0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1c100 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1c110 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1c120 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1c130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1c140 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1c150 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1c160 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1c170 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1c180 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1c190 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1c1a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1c1b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c1c0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1c1d0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1c1e0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1c1f0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1c200 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1c210 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1c220 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1c230 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1c240 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1c250 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c260 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
1c270 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1c280 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c290 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1c2a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c2b0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1c2c0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1c2d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1c2e0 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1c2f0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1c300 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1c310 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1c320 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1c330 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1c340 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1c350 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1c360 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1c370 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1c380 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1c390 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1c3a0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1c3b0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1c3c0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1c3d0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1c3e0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1c3f0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1c400 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1c410 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1c420 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1c430 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1c440 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1c450 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1c460 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1c470 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1c480 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1c490 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1c4a0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
1c4b0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
1c4c0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
1c4d0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
1c4e0 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
1c4f0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1c500 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1c510 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
1c520 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1c530 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1c540 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1c550 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1c560 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
1c570 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
1c580 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1c590 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1c5a0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1c5b0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1c5c0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1c5d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1c5e0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1c5f0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
1c600 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1c610 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1c620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c630 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1c640 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1c650 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1c660 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1c670 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1c680 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1c690 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1c6a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c6b0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1c6c0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1c6d0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1c6e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c6f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1c700 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1c710 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1c720 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1c730 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1c740 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1c750 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c760 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1c770 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1c780 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c790 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1c7a0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1c7b0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1c7c0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1c7d0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1c7e0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1c7f0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1c800 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1c810 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c820 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1c830 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1c840 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1c850 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1c860 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c870 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1c880 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1c890 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1c8a0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1c8b0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1c8c0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1c8d0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1c8e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1c8f0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1c900 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1c910 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1c920 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1c930 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1c940 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1c950 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1c960 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1c970 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c980 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1c990 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1c9a0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1c9b0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1c9c0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1c9d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1c9e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c9f0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1ca00 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1ca10 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1ca20 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1ca30 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1ca40 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1ca50 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1ca60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1ca70 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1ca80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1ca90 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1caa0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1cab0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1cac0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1cad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1cae0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1caf0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1cb00 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1cb10 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1cb20 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1cb30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1cb40 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1cb50 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1cb60 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1cb70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1cb80 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1cb90 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1cba0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1cbb0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1cbc0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1cbd0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1cbe0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1cbf0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1cc00 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1cc10 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1cc20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1cc30 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1cc40 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1cc50 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1cc60 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1cc70 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1cc80 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1cc90 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1cca0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1ccb0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1ccc0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1ccd0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1cce0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1ccf0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1cd00 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1cd10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1cd20 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1cd30 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1cd40 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1cd50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1cd60 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1cd70 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1cd80 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1cd90 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1cda0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1cdb0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1cdc0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1cdd0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1cde0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1cdf0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1ce00 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1ce10 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1ce20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1ce30 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1ce40 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1ce50 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1ce60 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1ce70 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1ce80 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1ce90 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1cea0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1ceb0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1cec0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1ced0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1cee0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1cef0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1cf00 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1cf10 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1cf20 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1cf30 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1cf40 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1cf50 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1cf60 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1cf70 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1cf80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1cf90 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1cfa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1cfb0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1cfc0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1cfd0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1cfe0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1cff0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1d000 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1d010 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1d020 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1d030 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1d040 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1d050 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1d060 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1d070 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1d080 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1d090 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1d0a0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1d0b0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1d0c0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1d0d0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1d0e0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1d0f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1d100 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1d110 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1d120 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1d130 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1d140 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d150 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1d160 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1d170 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1d180 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1d190 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1d1a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1d1b0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1d1c0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1d1d0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1d1e0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1d1f0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1d200 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1d210 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1d220 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1d230 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1d240 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1d250 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1d260 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1d270 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1d280 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1d290 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1d2a0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1d2b0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1d2c0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1d2d0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1d2e0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1d2f0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1d300 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1d310 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1d320 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1d330 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1d340 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1d350 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1d360 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1d370 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1d380 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1d390 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1d3a0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1d3b0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1d3c0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1d3d0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1d3e0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1d3f0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1d400 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1d410 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1d420 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1d430 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1d440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1d450 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1d460 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d470 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1d480 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d490 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1d4a0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1d4b0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1d4c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d4d0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1d4e0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1d4f0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1d500 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1d510 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d520 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1d530 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1d540 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1d550 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1d560 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1d570 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1d580 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1d590 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1d5a0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1d5b0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1d5c0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1d5d0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1d5e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d5f0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1d600 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1d610 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1d620 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1d630 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d640 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1d650 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1d660 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d670 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1d680 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1d690 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1d6a0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1d6b0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1d6c0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1d6d0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1d6e0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1d6f0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1d700 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1d710 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1d720 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1d730 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1d740 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1d750 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1d760 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
1d770 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1d780 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1d790 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1d7a0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1d7b0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1d7c0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1d7d0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1d7e0 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1d7f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d800 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1d810 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1d820 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1d830 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1d840 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d850 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1d860 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1d870 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1d880 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1d890 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1d8a0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1d8b0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1d8c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1d8d0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1d8e0 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1d8f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1d900 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1d910 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1d920 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1d930 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1d940 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1d950 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1d960 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1d970 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  a [SQLITE_ROLLBA
1d980 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65  CK | return code
1d990 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73  ].** from the [s
1d9a0 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
1d9b0 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
1d9c0 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
1d9d0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1d9e0 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1d9f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1da00 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1da10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1da20 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1da30 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1da40 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1da50 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1da60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1da70 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1da80 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1da90 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1daa0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
1dab0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
1dac0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1dad0 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
1dae0 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
1daf0 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
1db00 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
1db10 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
1db20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1db30 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1db40 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
1db50 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1db60 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
1db70 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1db80 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
1db90 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
1dba0 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
1dbb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1dbc0 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
1dbd0 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
1dbe0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
1dbf0 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
1dc00 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
1dc10 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
1dc20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1dc30 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
1dc40 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
1dc50 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1dc60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1dc70 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1dc80 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1dc90 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1dca0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1dcb0 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1dcc0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1dcd0 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1dce0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1dcf0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1dd00 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1dd10 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1dd20 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1dd30 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1dd40 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1dd50 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1dd60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1dd70 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1dd80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1dd90 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1dda0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1ddb0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1ddc0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1ddd0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1dde0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1ddf0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1de00 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1de10 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1de20 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1de30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1de40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1de50 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1de60 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1de70 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1de80 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1de90 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1dea0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1deb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ded0 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1dee0 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1def0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1df00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1df10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1df20 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1df30 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1df40 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1df50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1df60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1df70 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1df80 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1df90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1dfa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1dfb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1dfc0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1dfd0 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1dfe0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1dff0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e010 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1e020 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1e030 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1e040 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e060 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1e070 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1e080 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1e090 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e0a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e0b0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1e0c0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1e0d0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1e0e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e0f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1e100 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1e110 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1e120 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e130 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e140 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1e150 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1e160 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1e170 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1e180 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e190 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1e1a0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1e1b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e1c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e1d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e1e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1e1f0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1e200 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1e210 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1e220 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e230 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1e240 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1e250 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e260 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e270 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e280 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1e290 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1e2a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1e2b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e2c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e2d0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1e2e0 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1e2f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1e300 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e310 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e320 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1e330 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1e340 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1e350 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e360 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e370 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1e380 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1e390 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1e3a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e3b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e3c0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1e3d0 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
1e3e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e3f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e410 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
1e420 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
1e430 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
1e440 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
1e450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e460 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
1e470 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
1e480 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1e490 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1e4a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1e4b0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1e4c0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
1e4d0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1e4e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e4f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1e500 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
1e510 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
1e520 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
1e530 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
1e550 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
1e560 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
1e570 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1e580 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1e590 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
1e5a0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1e5b0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
1e5c0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
1e5d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e5e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
1e5f0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1e600 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
1e610 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
1e620 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e630 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
1e640 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1e650 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
1e660 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
1e670 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e680 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
1e690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
1e6a0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1e6b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e6c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e6d0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
1e6e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
1e6f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e700 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e710 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e720 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
1e730 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
1e740 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e750 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1e760 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e770 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1e780 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1e790 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e7a0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1e7b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e7c0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1e7d0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1e7e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1e7f0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1e800 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e810 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1e820 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1e830 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1e840 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1e850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e860 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1e870 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1e880 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1e890 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1e8a0 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1e8b0 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1e8c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1e8d0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1e8e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e8f0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1e900 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1e910 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1e920 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1e930 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1e940 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1e950 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1e960 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1e970 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1e980 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1e990 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1e9a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e9b0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1e9c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1e9d0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1e9e0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1e9f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1ea00 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1ea10 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1ea20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1ea30 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1ea40 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1ea50 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1ea60 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1ea70 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1ea80 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1ea90 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1eaa0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1eab0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1eac0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1ead0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1eae0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1eaf0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1eb00 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1eb10 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1eb20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1eb30 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1eb40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1eb50 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1eb60 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1eb70 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1eb80 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1eb90 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1eba0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1ebb0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1ebc0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1ebd0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1ebe0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1ebf0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1ec00 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1ec10 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1ec20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1ec30 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1ec40 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1ec50 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1ec60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1ec70 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1ec80 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1ec90 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1eca0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1ecb0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1ecc0 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1ecd0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1ece0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1ecf0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1ed00 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1ed10 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1ed20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1ed30 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1ed40 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1ed50 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1ed60 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1ed70 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1ed80 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1ed90 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1eda0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1edb0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1edc0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1edd0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1ede0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1edf0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1ee00 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1ee10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1ee20 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1ee30 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1ee40 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1ee50 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1ee60 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1ee70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ee80 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1ee90 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1eea0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1eeb0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1eec0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1eed0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1eee0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1eef0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1ef00 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1ef10 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1ef20 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1ef30 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1ef40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ef50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1ef60 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1ef70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ef80 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1ef90 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1efa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1efb0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1efc0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1efd0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1efe0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1eff0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1f000 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1f010 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1f020 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1f030 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1f040 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1f050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1f060 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1f070 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1f080 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1f090 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1f0a0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1f0b0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1f0c0 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20  llback X..**.** 
1f0d0 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1f0e0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1f0f0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1f100 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1f110 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1f120 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1f130 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1f140 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1f150 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1f160 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1f170 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1f180 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1f190 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1f1a0 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1f1b0 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1f1c0 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1f1d0 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1f1e0 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1f1f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1f200 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1f210 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1f220 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1f230 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1f240 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1f250 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1f260 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1f270 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1f280 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1f290 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1f2a0 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1f2b0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1f2c0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1f2d0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1f2e0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1f2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f300 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1f310 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f320 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1f330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f340 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1f350 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1f360 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1f370 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1f380 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1f390 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1f3a0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1f3b0 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1f3c0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1f3d0 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1f3e0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1f3f0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1f400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f410 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1f420 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1f430 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1f440 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1f450 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1f460 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
1f470 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
1f480 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
1f490 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
1f4a0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
1f4b0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
1f4c0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1f4d0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1f4e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
1f4f0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1f500 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
1f510 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
1f520 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
1f530 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f540 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
1f550 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
1f560 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
1f570 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
1f580 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
1f590 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
1f5a0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
1f5b0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1f5c0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
1f5d0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
1f5e0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
1f5f0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
1f600 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
1f610 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1f620 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1f630 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1f640 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
1f650 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
1f660 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
1f670 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
1f680 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
1f690 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1f6a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
1f6b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1f6c0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
1f6d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f6e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f6f0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
1f700 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
1f710 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
1f720 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
1f730 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
1f740 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
1f750 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
1f760 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
1f770 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
1f780 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
1f790 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
1f7a0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
1f7b0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
1f7c0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
1f7d0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1f7e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1f7f0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
1f800 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1f810 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
1f820 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
1f830 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
1f840 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
1f850 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1f860 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
1f870 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
1f880 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1f890 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1f8a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1f8b0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
1f8c0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
1f8d0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
1f8e0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
1f8f0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
1f900 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1f910 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
1f920 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
1f930 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
1f940 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
1f950 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
1f960 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
1f970 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
1f980 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
1f990 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
1f9a0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1f9b0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
1f9c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
1f9d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
1f9e0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
1f9f0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
1fa00 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1fa10 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
1fa20 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1fa30 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1fa40 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1fa50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1fa60 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
1fa70 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1fa80 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
1fa90 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1faa0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
1fab0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
1fac0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
1fad0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1fae0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1faf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1fb00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1fb10 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1fb20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1fb30 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1fb40 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1fb50 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1fb60 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1fb70 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1fb80 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1fb90 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1fba0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1fbb0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1fbc0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1fbd0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1fbe0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1fbf0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1fc00 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1fc10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1fc20 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1fc30 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1fc40 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1fc50 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1fc60 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1fc70 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1fc80 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1fc90 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1fca0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1fcb0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1fcc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1fcd0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1fce0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1fcf0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1fd00 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
1fd10 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1fd20 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1fd30 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1fd40 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1fd50 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1fd60 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1fd70 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1fd80 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
1fd90 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
1fda0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1fdb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1fdc0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
1fdd0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
1fde0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
1fdf0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1fe00 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
1fe10 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1fe20 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
1fe30 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
1fe40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1fe50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1fe60 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
1fe70 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
1fe80 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
1fe90 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1fea0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
1feb0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
1fec0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
1fed0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
1fee0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
1fef0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
1ff00 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
1ff10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1ff20 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
1ff30 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
1ff40 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1ff50 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
1ff60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1ff70 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
1ff80 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
1ff90 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
1ffa0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
1ffb0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
1ffc0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
1ffd0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
1ffe0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1fff0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
20000 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20010 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
20020 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
20030 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
20040 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
20050 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
20060 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
20070 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
20080 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
20090 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
200a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
200b0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
200c0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
200d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
200e0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
200f0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
20100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20110 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
20120 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
20130 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
20140 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
20150 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
20160 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
20170 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20180 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
20190 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
201a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
201b0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
201c0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
201d0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
201e0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
201f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20200 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
20210 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
20220 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
20230 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
20240 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
20250 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
20260 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
20270 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
20280 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
20290 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
202a0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
202b0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
202c0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
202d0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
202e0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
202f0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
20300 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
20310 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20320 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
20330 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
20340 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
20350 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
20360 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
20370 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
20380 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
20390 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
203a0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
203b0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
203c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
203d0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
203e0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
203f0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
20400 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
20410 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
20420 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
20430 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
20440 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
20450 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20460 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
20470 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
20480 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
20490 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
204a0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
204b0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
204c0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
204d0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
204e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
204f0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
20500 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20510 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
20520 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
20530 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
20540 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
20550 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
20560 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
20570 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
20580 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
20590 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
205a0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
205b0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
205c0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
205d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
205e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
205f0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
20600 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
20610 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
20620 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
20630 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
20640 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
20650 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
20660 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
20670 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
20680 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
20690 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
206a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
206b0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
206c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
206d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
206e0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
206f0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
20700 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
20710 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
20720 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
20730 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
20740 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
20750 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
20760 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
20770 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
20780 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
20790 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
207a0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
207b0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
207c0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
207d0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
207e0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
207f0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
20800 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
20810 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
20820 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
20830 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
20840 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
20850 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
20860 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
20870 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
20880 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
20890 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
208a0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
208b0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
208c0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
208d0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
208e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
208f0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
20900 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
20910 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
20920 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
20930 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
20940 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
20950 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
20960 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
20970 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
20980 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
20990 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
209a0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
209b0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
209c0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
209d0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
209e0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
209f0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
20a00 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
20a10 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
20a20 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
20a30 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
20a40 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
20a50 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
20a60 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
20a70 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
20a80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
20a90 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
20aa0 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  ** ^On windows, 
20ab0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
20ac0 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
20ad0 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
20ae0 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
20af0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
20b00 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ..**.** [[core U
20b10 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
20b20 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
20b30 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
20b40 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
20b50 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
20b60 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
20b70 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
20b80 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
20b90 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
20ba0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
20bb0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
20bc0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
20bd0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
20be0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
20bf0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
20c00 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
20c10 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
20c20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
20c30 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
20c40 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
20c50 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
20c60 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
20c70 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20c80 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
20c90 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
20ca0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
20cb0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
20cc0 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
20cd0 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
20ce0 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
20cf0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
20d00 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
20d10 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
20d20 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
20d30 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
20d40 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
20d50 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
20d60 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
20d70 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
20d80 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
20d90 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
20da0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
20db0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
20dc0 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
20dd0 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
20de0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
20df0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
20e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20e10 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
20e20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
20e30 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
20e40 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
20e50 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
20e60 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
20e70 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
20e80 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
20e90 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
20ea0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
20eb0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
20ec0 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
20ed0 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
20ee0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
20ef0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
20f00 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
20f10 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
20f20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
20f30 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
20f40 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
20f50 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
20f60 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
20f70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
20f80 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
20f90 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
20fa0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
20fb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
20fc0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
20fd0 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
20fe0 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
20ff0 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
21000 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
21010 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
21020 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
21030 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
21040 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
21050 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
21060 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
21070 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
21080 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21090 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
210a0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
210b0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
210c0 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
210d0 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
210e0 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
210f0 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
21100 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
21110 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
21120 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
21130 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
21140 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
21150 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
21160 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
21170 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
21180 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
21190 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
211a0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
211b0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
211c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
211d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
211e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
211f0 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
21200 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
21210 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
21220 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
21230 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
21240 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
21250 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
21260 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
21270 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
21280 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
21290 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
212a0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
212b0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
212c0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
212d0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
212e0 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
212f0 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
21300 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
21310 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
21320 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
21330 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21340 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
21350 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21360 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
21370 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
21380 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
21390 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
213a0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
213b0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
213c0 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
213d0 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
213e0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
213f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
21400 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
21410 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
21420 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
21430 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
21440 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
21450 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
21460 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
21470 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
21480 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
21490 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
214a0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
214b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
214c0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
214d0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
214e0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
214f0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
21500 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
21510 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
21520 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
21530 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
21540 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
21550 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
21560 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
21570 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
21580 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
21590 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
215a0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
215b0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
215c0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
215d0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
215e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
215f0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
21600 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
21610 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
21620 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21630 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
21640 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
21650 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
21660 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
21670 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
21680 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
21690 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
216a0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
216b0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
216c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
216d0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
216e0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
216f0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
21700 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
21710 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
21720 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
21730 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
21740 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
21750 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
21760 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
21770 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
21780 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
21790 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
217a0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
217b0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
217c0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
217d0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
217e0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
217f0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
21800 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
21810 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
21820 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
21830 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
21840 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
21850 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
21860 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
21870 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
21880 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
21890 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
218a0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
218b0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
218c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
218d0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
218e0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
218f0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21900 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
21910 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
21920 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
21930 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
21940 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
21950 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
21960 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
21970 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
21980 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
21990 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
219a0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
219b0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
219c0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
219d0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
219e0 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a  nix-nolock <td>.
219f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
21a00 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
21a10 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
21a20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
21a30 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a  "unix-nolock"..*
21a40 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21a50 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
21a60 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
21a70 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
21a80 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
21a90 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
21aa0 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
21ab0 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
21ac0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
21ad0 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
21ae0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
21af0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
21b00 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
21b10 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
21b20 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
21b30 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
21b40 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
21b50 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
21b60 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
21b70 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
21b80 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
21b90 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
21ba0 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
21bb0 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
21bc0 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
21bd0 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
21be0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
21bf0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
21c00 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
21c10 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
21c20 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
21c30 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
21c40 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
21c50 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
21c60 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
21c70 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
21c80 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
21c90 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
21ca0 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
21cb0 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
21cc0 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
21cd0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
21ce0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
21cf0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
21d00 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
21d10 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
21d20 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
21d30 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
21d40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21d50 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21d60 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
21d70 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
21d80 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
21d90 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
21da0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
21db0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
21dc0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
21dd0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
21de0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
21df0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
21e00 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
21e10 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
21e20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21e30 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
21e40 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
21e50 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
21e60 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
21e70 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
21e80 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
21e90 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
21ea0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
21eb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
21ec0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
21ed0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
21ee0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
21ef0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
21f00 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
21f10 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
21f20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
21f30 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
21f40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
21f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
21f60 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
21f70 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
21f80 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
21f90 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
21fa0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
21fb0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
21fc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
21fd0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
21fe0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
21ff0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
22000 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
22010 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
22020 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
22030 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
22040 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
22050 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
22060 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
22070 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
22080 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22090 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
220a0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
220b0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
220c0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
220d0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
220e0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
220f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
22100 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
22110 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
22120 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
22130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22140 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
22150 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
22160 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
22170 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
22180 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
22190 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
221a0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
221b0 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
221c0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
221d0 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
221e0 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
221f0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
22200 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
22210 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
22220 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
22230 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
22240 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
22250 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
22260 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
22270 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
22280 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
22290 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
222a0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
222b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
222c0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
222d0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
222e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
222f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
22300 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
22310 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
22320 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22330 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
22340 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
22350 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
22360 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
22370 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
22380 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
22390 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
223a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
223b0 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
223c0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
223d0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
223e0 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
223f0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
22400 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
22410 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
22420 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
22430 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
22440 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
22450 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
22470 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22480 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
22490 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
224a0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
224b0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
224c0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
224d0 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
224e0 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
224f0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
22500 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22510 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
22520 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
22530 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
22540 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
22550 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
22560 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
22570 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
22580 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
22590 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
225a0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
225b0 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
225c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
225d0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
225e0 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
225f0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
22600 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
22610 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
22620 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
22630 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
22640 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
22650 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
22660 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
22670 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
22680 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
22690 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
226a0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
226b0 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
226c0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
226d0 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
226e0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
226f0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
22700 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
22710 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
22720 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
22730 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
22740 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
22750 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
22760 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
22770 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
22780 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
22790 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
227a0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
227b0 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
227c0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
227d0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
227e0 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
227f0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
22800 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
22810 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
22820 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
22830 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
22840 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
22850 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22860 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
22870 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
22880 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
22890 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
228a0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
228b0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
228c0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
228d0 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
228e0 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
228f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
22900 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
22910 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
22920 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
22930 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
22940 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
22950 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
22960 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
22970 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
22980 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
22990 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
229a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
229b0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
229c0 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
229d0 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
229e0 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
229f0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
22a00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
22a10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
22a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22a30 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
22a40 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
22a50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
22a60 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
22a70 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
22a80 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
22a90 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
22aa0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
22ab0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
22ac0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
22ad0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
22ae0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
22af0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
22b00 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
22b10 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
22b20 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
22b30 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
22b40 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
22b50 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
22b60 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
22b70 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
22b80 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
22b90 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
22ba0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
22bb0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
22bc0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
22bd0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
22be0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
22bf0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
22c00 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
22c10 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
22c20 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
22c30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
22c40 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
22c50 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
22c60 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
22c70 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
22c80 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
22c90 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
22ca0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
22cb0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
22cc0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
22cd0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
22ce0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
22cf0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
22d00 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
22d10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
22d20 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
22d30 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
22d40 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
22d50 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
22d60 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
22d70 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
22d80 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
22d90 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
22da0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
22db0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
22dc0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
22dd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22de0 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
22df0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
22e00 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
22e10 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
22e20 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
22e30 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
22e40 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
22e50 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
22e60 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
22e70 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
22e80 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
22e90 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
22ea0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
22eb0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
22ec0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
22ed0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
22ee0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
22ef0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
22f00 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
22f10 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
22f20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
22f30 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
22f40 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
22f50 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
22f60 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
22f70 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
22f80 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
22f90 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
22fa0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
22fb0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
22fc0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
22fd0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
22fe0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
22ff0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
23000 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
23010 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
23020 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
23030 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
23040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
23050 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
23060 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
23070 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
23080 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
23090 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
230a0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
230b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
230c0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
230d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
230e0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
230f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
23100 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
23110 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
23120 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
23130 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
23140 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
23150 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
23160 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
23170 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
23180 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
23190 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
231a0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
231b0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
231c0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
231d0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
231e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
231f0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
23200 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
23210 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
23220 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
23230 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23240 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
23250 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
23260 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
23270 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
23280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23290 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
232a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
232b0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
232c0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
232d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
232e0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
232f0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
23300 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
23310 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
23320 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
23330 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
23340 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
23350 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
23360 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
23370 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
23380 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
23390 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
233a0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
233b0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
233c0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
233d0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
233e0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
233f0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
23400 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
23410 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
23420 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
23430 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
23440 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
23450 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
23460 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
23470 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
23480 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
23490 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
234a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
234b0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
234c0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
234d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
234e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
234f0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
23500 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
23510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
23520 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
23530 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
23540 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
23550 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
23560 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
23570 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
23580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
23590 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
235a0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
235b0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
235c0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
235d0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
235e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
235f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23600 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
23610 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
23620 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
23630 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
23640 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
23650 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
23660 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
23670 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
23680 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
23690 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
236a0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
236b0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
236c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
236d0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
236e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
236f0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
23700 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
23710 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
23720 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
23730 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
23740 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
23750 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
23760 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
23770 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
23780 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
23790 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
237a0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
237b0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
237c0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
237d0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
237e0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
237f0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
23800 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
23810 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
23820 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
23830 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
23840 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
23850 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
23860 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
23870 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
23880 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
23890 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
238a0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
238b0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
238c0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
238d0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
238e0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
238f0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
23900 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
23910 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
23920 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
23930 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
23940 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
23950 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
23960 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
23970 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
23980 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23990 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
239a0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
239b0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
239c0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
239d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
239e0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
239f0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
23a00 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
23a10 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
23a20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
23a30 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
23a40 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
23a50 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
23a60 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
23a70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
23a80 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
23a90 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
23aa0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
23ab0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
23ac0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
23ad0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
23ae0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
23af0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
23b00 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
23b10 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
23b20 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
23b30 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
23b40 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
23b50 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
23b60 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
23b70 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
23b80 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
23b90 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
23ba0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
23bb0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
23bc0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
23bd0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
23be0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
23bf0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
23c00 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
23c10 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
23c20 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
23c30 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
23c40 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
23c50 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
23c60 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
23c70 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
23c80 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
23c90 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
23ca0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
23cb0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
23cc0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
23cd0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
23ce0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23cf0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
23d00 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
23d10 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
23d20 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
23d30 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
23d40 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
23d50 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
23d60 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
23d70 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
23d80 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
23d90 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
23da0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
23db0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
23dc0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
23dd0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
23de0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
23df0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
23e00 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
23e10 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
23e20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
23e30 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
23e40 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
23e50 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
23e60 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
23e70 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
23e80 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
23e90 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
23ea0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
23eb0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
23ec0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
23ed0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23ee0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
23ef0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
23f00 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
23f10 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
23f20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
23f30 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
23f40 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
23f50 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
23f60 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
23f70 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
23f80 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
23f90 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
23fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23fb0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
23fc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
23fd0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
23fe0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
23ff0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
24000 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
24010 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
24020 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
24030 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
24040 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
24050 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24060 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
24070 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
24080 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
24090 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
240a0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
240b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
240c0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
240d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
240e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
240f0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
24100 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
24110 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
24120 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
24130 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
24140 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
24150 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
24160 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
24170 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
24180 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24190 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
241a0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
241b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
241c0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
241d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
241e0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
241f0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
24200 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
24210 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24220 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
24230 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
24240 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
24250 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
24260 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24270 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
24280 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
24290 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
242a0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
242b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
242c0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
242d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
242e0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
242f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24300 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
24310 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
24320 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
24330 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
24340 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
24350 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
24360 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
24370 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
24380 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
24390 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
243a0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
243b0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
243c0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
243d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
243e0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
243f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24400 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
24410 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24420 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
24430 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
24440 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
24450 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24460 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
24470 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24480 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
24490 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
244a0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
244b0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
244c0 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
244d0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
244e0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
244f0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
24500 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24510 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24520 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
24530 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24540 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
24550 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
24560 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
24570 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
24580 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
24590 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
245a0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
245b0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
245c0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
245d0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
245e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
245f0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
24600 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
24610 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
24620 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
24630 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
24640 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
24650 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24660 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
24670 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24680 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
24690 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
246a0 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
246b0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
246c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
246d0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
246e0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
246f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24700 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
24710 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
24720 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24730 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
24740 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
24750 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24760 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
24770 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
24780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24790 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
247a0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
247b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
247c0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
247d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
247e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
247f0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
24800 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
24810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24820 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
24830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24840 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
24850 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
24860 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
24870 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
24880 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
24890 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
248a0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
248b0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
248c0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
248d0 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
248e0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
248f0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
24900 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
24910 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
24920 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
24930 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
24940 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
24950 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
24960 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
24970 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
24980 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
24990 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
249a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
249b0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
249c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
249d0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
249e0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
249f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
24a00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
24a10 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
24a20 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
24a30 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
24a40 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
24a50 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
24a60 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
24a70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
24a80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
24a90 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
24aa0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
24ab0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
24ac0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
24ad0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
24ae0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
24af0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
24b00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
24b10 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
24b20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
24b30 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
24b40 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
24b50 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
24b60 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
24b70 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
24b80 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
24b90 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
24ba0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
24bb0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
24bc0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
24bd0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
24be0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
24bf0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
24c00 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
24c10 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
24c20 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
24c30 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
24c40 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
24c50 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
24c60 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
24c70 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
24c80 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
24c90 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
24ca0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
24cb0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
24cc0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
24cd0 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
24ce0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
24cf0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
24d00 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
24d10 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
24d20 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
24d30 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
24d40 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
24d50 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
24d60 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
24d70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24d80 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
24d90 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
24da0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
24db0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
24dc0 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
24dd0 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
24de0 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
24df0 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
24e00 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
24e10 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
24e20 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
24e30 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
24e40 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
24e50 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
24e60 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
24e70 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
24e80 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
24e90 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
24ea0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
24eb0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
24ec0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
24ed0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
24ee0 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
24ef0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
24f00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
24f10 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
24f20 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
24f30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24f40 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
24f50 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
24f60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24f70 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
24f80 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
24f90 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
24fa0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
24fb0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
24fc0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
24fd0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
24fe0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
24ff0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
25000 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
25010 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
25020 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
25030 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
25040 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
25050 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
25060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
25070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
25080 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
25090 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
250a0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
250b0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
250c0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
250d0 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
250e0 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
250f0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
25100 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
25110 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
25120 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
25130 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25140 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25150 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
25160 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25170 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
25180 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
25190 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
251a0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
251b0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
251c0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
251d0 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
251e0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
251f0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
25200 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
25210 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
25220 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
25230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25240 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
25250 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
25260 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
25270 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
25280 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
25290 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
252a0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
252b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
252c0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
252d0 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
252e0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
252f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
25300 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
25310 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
25320 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
25330 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
25340 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
25350 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
25360 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
25370 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
25380 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
25390 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
253a0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
253b0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
253c0 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  again..** </li>.
253d0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
253e0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
253f0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
25400 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
25410 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
25420 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
25430 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
25440 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
25450 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
25460 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
25470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
25480 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
25490 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
254a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
254b0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
254c0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
254d0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
254e0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
254f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25500 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
25510 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
25520 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
25530 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
25540 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
25550 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
25560 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
25570 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
25580 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
25590 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
255a0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
255b0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
255c0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
255d0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
255e0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
255f0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
25600 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
25610 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
25620 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
25630 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
25640 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
25650 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
25660 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
25670 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
25680 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
25690 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
256a0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
256b0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
256c0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
256d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
256e0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
256f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25700 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
25710 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
25720 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
25730 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
25740 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
25750 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
25760 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
25770 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
25780 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
25790 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
257a0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
257b0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
257c0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
257d0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
257e0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
257f0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
25800 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
25810 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
25820 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
25830 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
25840 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
25850 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
25860 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25870 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
25880 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
25890 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
258a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
258b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
258c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
258d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
258e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
258f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
25900 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25910 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
25920 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
25930 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
25940 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
25950 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25960 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
25970 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
25980 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
25990 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
259a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
259b0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
259c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
259d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
259e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
259f0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
25a00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
25a10 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
25a20 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
25a30 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
25a40 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
25a50 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
25a60 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
25a70 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
25a80 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
25a90 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
25aa0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
25ab0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
25ac0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
25ad0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
25ae0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
25af0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
25b00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
25b10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
25b20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
25b30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
25b40 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
25b50 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
25b60 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
25b70 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25b80 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25b90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25ba0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25bb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25bc0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25bd0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25be0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25bf0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
25c00 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25c10 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25c20 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
25c30 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
25c40 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
25c50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
25c60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
25c70 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25c80 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
25c90 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
25ca0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
25cb0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
25cc0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
25cd0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
25ce0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
25cf0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
25d00 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
25d10 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
25d20 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
25d30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
25d40 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
25d50 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
25d60 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
25d70 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
25d80 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
25d90 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
25da0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
25db0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
25dc0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
25dd0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
25de0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
25df0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
25e00 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
25e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
25e20 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
25e30 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
25e40 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
25e50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25e60 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
25e70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
25e80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
25e90 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
25ea0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
25eb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25ec0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
25ed0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
25ee0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
25ef0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
25f00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
25f10 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
25f20 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
25f30 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
25f40 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
25f50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25f60 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
25f70 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
25f80 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
25f90 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
25fa0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
25fb0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
25fc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25fd0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
25fe0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
25ff0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
26000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
26010 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
26020 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
26030 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
26040 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
26050 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
26060 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
26070 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
26080 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
26090 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
260a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
260b0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
260c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
260d0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
260e0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
260f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
26100 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
26110 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
26120 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
26130 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
26140 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
26150 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
26160 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
26170 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
26180 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
26190 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
261a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
261b0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
261c0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
261d0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
261e0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
261f0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
26200 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
26210 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
26220 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
26230 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
26240 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26250 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
26260 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
26270 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
26280 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
26290 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
262a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
262b0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
262c0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
262d0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
262e0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
262f0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
26300 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
26310 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
26320 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
26330 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
26340 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26350 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
26360 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
26370 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
26380 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
26390 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
263a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
263b0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
263c0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
263d0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
263e0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
263f0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
26400 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
26410 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
26420 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
26430 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26440 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
26450 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
26460 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
26470 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
26480 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
26490 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
264a0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
264b0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
264c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
264d0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
264e0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
264f0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
26500 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
26510 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
26520 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
26530 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
26540 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
26550 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
26560 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
26570 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
26580 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
26590 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
265a0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
265b0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
265c0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
265d0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
265e0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
265f0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
26600 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
26610 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
26620 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
26630 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
26640 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
26650 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
26660 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26670 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
26680 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
26690 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
266a0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
266b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
266c0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
266d0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
266e0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
266f0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
26700 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
26710 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
26720 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
26730 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
26740 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
26750 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
26760 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
26770 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
26780 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
26790 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
267a0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
267b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
267c0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
267d0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
267e0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
267f0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
26800 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
26810 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26820 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
26830 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
26840 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26850 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
26860 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
26870 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
26880 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
26890 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
268a0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
268b0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
268c0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
268d0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
268e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
268f0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
26900 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
26910 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
26920 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
26930 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
26940 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
26950 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
26960 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
26970 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
26980 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
26990 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
269a0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
269b0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
269c0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
269d0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
269e0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
269f0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
26a00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
26a10 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
26a20 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
26a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
26a40 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
26a50 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
26a60 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
26a70 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
26a80 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
26a90 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
26aa0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
26ab0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
26ac0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
26ad0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
26ae0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
26af0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
26b00 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
26b10 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26b20 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
26b30 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
26b40 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
26b50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26b60 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
26b70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
26b80 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
26b90 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
26ba0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
26bb0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
26bc0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
26bd0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
26be0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
26bf0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
26c00 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
26c10 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
26c20 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
26c30 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
26c40 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
26c50 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
26c60 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
26c70 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
26c80 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
26c90 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
26ca0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26cb0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
26cc0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
26cd0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
26ce0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
26cf0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
26d00 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
26d10 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
26d20 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
26d30 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
26d40 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
26d50 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
26d60 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
26d70 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
26d80 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
26d90 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
26da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26db0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
26dc0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
26dd0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
26de0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
26df0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
26e00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26e10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
26e20 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
26e30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26e40 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
26e50 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
26e60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
26e70 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
26e80 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
26e90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26ea0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
26eb0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
26ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
26ed0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
26ee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
26ef0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
26f00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
26f10 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
26f20 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
26f30 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
26f40 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
26f50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26f60 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
26f70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
26f80 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
26f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26fa0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
26fb0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
26fc0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
26fd0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
26fe0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
26ff0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
27000 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
27010 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
27020 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
27030 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
27040 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
27050 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
27060 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
27070 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
27080 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
27090 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
270a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
270b0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
270c0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
270d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
270e0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
270f0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
27100 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
27110 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
27120 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27130 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
27140 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27150 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
27160 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
27170 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
27180 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
27190 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
271a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
271b0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
271c0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
271d0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
271e0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
271f0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
27200 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
27210 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
27220 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
27230 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
27240 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
27250 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
27260 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
27270 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
27280 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
27290 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
272a0 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
272b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
272c0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
272d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
272e0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
272f0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
27300 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
27310 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
27320 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
27330 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
27340 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
27350 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
27360 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
27370 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
27380 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
27390 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
273a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
273b0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
273c0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
273d0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
273e0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
273f0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
27400 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
27410 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
27420 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
27430 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
27440 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
27450 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
27460 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
27470 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
27480 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
27490 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
274a0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
274b0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
274c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
274d0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
274e0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
274f0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
27500 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
27510 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
27520 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
27530 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
27540 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27550 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
27560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
27570 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
27580 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
27590 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
275a0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
275b0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
275c0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
275d0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
275e0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
275f0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
27600 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
27610 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
27620 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
27630 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
27640 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
27650 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
27660 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
27670 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
27680 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
27690 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
276a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
276b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
276c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
276d0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
276e0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
276f0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
27700 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
27710 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
27720 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
27730 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
27740 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
27750 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
27760 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
27770 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27780 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
27790 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
277a0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
277b0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
277c0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
277d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
277e0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
277f0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
27800 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
27810 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
27820 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
27830 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
27840 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
27850 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
27860 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
27870 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
27880 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
27890 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
278a0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
278b0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
278c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
278d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
278e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
278f0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
27900 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
27910 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
27920 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
27930 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27940 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
27950 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
27960 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
27970 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
27980 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
27990 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
279a0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
279b0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
279c0 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
279d0 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
279e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
279f0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
27a00 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
27a10 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
27a20 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74  _text16() then t
27a30 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
27a40 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
27a50 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
27a60 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
27a70 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
27a80 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
27a90 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
27aa0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
27ab0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
27ac0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
27ad0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
27ae0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
27af0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
27b00 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
27b10 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
27b20 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
27b30 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
27b40 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
27b50 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
27b60 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
27b70 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
27b80 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
27b90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
27ba0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
27bb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
27bc0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
27bd0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
27be0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
27bf0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
27c00 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
27c10 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
27c20 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
27c30 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
27c40 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
27c50 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
27c60 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
27c70 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
27c80 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
27c90 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
27ca0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
27cb0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
27cc0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
27cd0 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
27ce0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
27cf0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
27d00 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
27d10 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
27d20 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
27d30 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
27d40 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
27d50 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
27d60 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
27d70 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
27d80 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
27d90 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
27da0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
27db0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
27dc0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
27dd0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
27de0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
27df0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
27e00 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
27e10 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
27e20 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
27e30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
27e40 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
27e50 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
27e60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
27e70 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
27e80 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
27e90 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
27ea0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
27eb0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
27ec0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
27ed0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
27ee0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
27ef0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
27f00 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
27f10 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
27f20 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
27f30 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
27f40 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
27f50 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
27f60 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
27f70 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
27f80 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
27f90 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
27fa0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
27fb0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
27fc0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
27fd0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
27fe0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
27ff0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
28000 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
28010 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
28020 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28030 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
28040 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
28050 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
28060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28070 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
28080 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28090 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
280a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
280b0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
280c0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
280d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
280e0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
280f0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
28100 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
28110 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
28120 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
28130 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
28140 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
28150 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
28160 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
28170 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
28180 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
28190 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
281a0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
281b0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
281c0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
281d0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
281e0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
281f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
28200 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
28210 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
28220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
28230 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
28240 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
28250 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
28260 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
28270 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
28280 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
28290 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
282a0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
282b0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
282c0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
282d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
282e0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
282f0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
28300 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
28310 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28320 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
28330 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28340 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
28350 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
28360 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
28370 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
28380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28390 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
283a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
283b0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
283c0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
283d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
283e0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
283f0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
28400 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28410 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
28420 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
28430 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28440 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
28450 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
28460 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
28470 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
28480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28490 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
284a0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
284b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
284c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
284d0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
284e0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
284f0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
28500 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28510 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
28520 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28530 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28540 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
28550 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28560 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
28570 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
28580 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
28590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
285a0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
285b0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
285c0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
285d0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
285e0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
285f0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
28600 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
28610 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
28620 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
28630 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
28640 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
28650 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
28660 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
28670 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
28680 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
28690 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
286a0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
286b0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
286c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
286d0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
286e0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
286f0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
28700 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
28710 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
28720 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
28730 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
28740 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
28750 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
28760 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
28770 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
28780 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
28790 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
287a0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
287b0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
287c0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
287d0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
287e0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
287f0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
28800 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
28810 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
28820 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
28830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28840 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
28850 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
28860 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28870 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
28880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28890 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
288a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
288b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
288c0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
288d0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
288e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
288f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
28900 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
28910 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
28920 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
28930 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
28940 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
28950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
28960 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
28970 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
28980 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
28990 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
289a0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
289b0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
289c0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
289d0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
289e0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
289f0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
28a00 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
28a10 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
28a20 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
28a30 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
28a40 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
28a50 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
28a60 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
28a70 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
28a80 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
28a90 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
28aa0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
28ab0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
28ac0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
28ad0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
28ae0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
28af0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
28b00 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
28b10 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
28b20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
28b30 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
28b40 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
28b50 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
28b60 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
28b70 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
28b80 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
28b90 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
28ba0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
28bb0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
28bc0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
28bd0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
28be0 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
28bf0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
28c00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28c10 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
28c20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28c30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
28c40 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
28c50 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
28c60 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
28c70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28c80 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
28c90 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
28ca0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28cb0 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
28cc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
28cd0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
28ce0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28cf0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
28d00 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
28d10 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
28d20 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
28d30 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
28d40 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
28d50 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
28d60 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
28d70 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
28d80 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
28d90 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
28da0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
28db0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
28dc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
28dd0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
28de0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
28df0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
28e00 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
28e10 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
28e20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
28e30 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
28e40 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
28e50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
28e60 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
28e70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
28e80 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
28e90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28ea0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
28eb0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28ec0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
28ed0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
28ee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28ef0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
28f00 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
28f10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28f20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
28f30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
28f40 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
28f50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
28f60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
28f70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28f80 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
28f90 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
28fa0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
28fb0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
28fc0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
28fd0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
28fe0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
28ff0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
29000 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
29010 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
29020 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
29030 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
29040 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
29050 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
29060 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
29070 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
29080 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
29090 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
290a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
290b0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
290c0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
290d0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
290e0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
290f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
29100 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
29110 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
29120 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29130 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
29140 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
29150 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
29160 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
29170 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
29180 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
29190 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
291a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
291b0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
291c0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
291d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
291e0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
291f0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29200 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
29210 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
29220 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
29230 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
29240 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
29250 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
29260 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
29270 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
29280 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
29290 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
292a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
292b0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
292c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
292d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
292e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
292f0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
29300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29310 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
29320 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
29330 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
29340 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
29350 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
29360 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
29370 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29380 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
29390 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
293a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
293b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
293c0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
293d0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
293e0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
293f0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
29400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
29410 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
29420 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
29430 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
29440 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29450 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
29460 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
29470 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
29480 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
29490 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
294a0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
294b0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
294c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
294d0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
294e0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
294f0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
29500 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
29510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
29520 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
29530 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
29540 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
29550 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
29560 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
29570 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
29580 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
29590 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
295a0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
295b0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
295c0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
295d0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
295e0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
295f0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
29600 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
29610 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
29620 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
29630 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
29640 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
29650 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
29660 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
29670 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
29680 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
29690 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
296a0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
296b0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
296c0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
296d0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
296e0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
296f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29700 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
29710 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29720 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
29730 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29740 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
29750 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
29760 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
29770 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
29780 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
29790 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
297a0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
297b0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
297c0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
297d0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
297e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
297f0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
29800 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
29810 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
29820 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
29830 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
29840 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
29850 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
29860 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
29870 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
29880 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
29890 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
298a0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
298b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
298c0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
298d0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
298e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
298f0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
29900 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
29910 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
29920 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
29930 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
29940 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
29950 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
29960 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29970 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
29980 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
29990 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
299a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
299b0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
299c0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
299d0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
299e0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
299f0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
29a00 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
29a10 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
29a20 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
29a30 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
29a40 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
29a50 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
29a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
29a70 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
29a80 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
29a90 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
29aa0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
29ab0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
29ac0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
29ad0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
29ae0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
29af0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
29b00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
29b10 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
29b20 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
29b30 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
29b40 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
29b50 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
29b60 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
29b70 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
29b80 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
29b90 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
29ba0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
29bb0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
29bc0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
29bd0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
29be0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
29bf0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
29c00 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
29c10 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
29c20 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
29c30 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
29c40 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
29c50 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
29c60 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
29c70 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
29c80 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
29c90 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
29ca0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
29cb0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
29cc0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
29cd0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
29ce0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
29cf0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
29d00 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
29d10 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
29d20 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
29d30 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
29d40 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
29d50 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
29d60 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
29d70 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
29d80 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
29d90 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
29da0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
29db0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
29dc0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
29dd0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
29de0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
29df0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
29e00 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
29e10 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
29e20 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
29e30 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
29e40 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
29e50 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
29e60 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
29e70 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
29e80 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
29e90 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
29ea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
29eb0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
29ec0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
29ed0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
29ee0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
29ef0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
29f00 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
29f10 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
29f20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
29f30 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
29f40 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
29f50 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
29f60 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
29f70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
29f80 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
29f90 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
29fa0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
29fb0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
29fc0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
29fd0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
29fe0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
29ff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a000 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2a010 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a020 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2a030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a040 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2a050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a060 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2a070 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a080 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a090 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2a0a0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2a0b0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2a0c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a0d0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2a0e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a0f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2a100 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a110 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2a120 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a140 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2a150 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2a160 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2a170 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2a180 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2a190 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2a1a0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2a1b0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2a1c0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2a1d0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2a1e0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2a1f0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2a200 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2a210 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2a220 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2a230 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2a240 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2a250 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2a260 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2a270 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2a280 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2a290 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2a2a0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2a2b0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2a2c0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2a2d0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2a2e0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2a2f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2a300 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2a310 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2a320 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2a330 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2a340 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2a350 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2a360 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2a370 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2a380 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2a390 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2a3a0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2a3b0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2a3c0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2a3d0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2a3e0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2a3f0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2a400 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2a410 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2a420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2a430 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2a440 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2a450 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2a460 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2a470 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2a480 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2a490 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2a4a0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2a4b0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2a4c0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2a4d0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2a4e0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2a4f0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2a500 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2a510 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2a520 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2a530 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2a540 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2a550 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2a560 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2a570 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2a580 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2a590 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2a5a0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2a5b0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2a5c0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2a5d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2a5e0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2a5f0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2a600 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2a610 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2a620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a630 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a640 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2a650 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2a660 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2a670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a680 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2a690 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2a6a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2a6b0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2a6c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a6d0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2a6e0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2a6f0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2a700 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2a710 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a720 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2a730 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2a740 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2a750 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2a760 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2a770 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2a780 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2a790 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2a7a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2a7b0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2a7c0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2a7d0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2a7e0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2a7f0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2a800 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2a810 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a820 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2a830 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2a840 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2a850 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2a860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a870 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2a880 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2a890 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2a8a0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2a8b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2a8c0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2a8d0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2a8e0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2a8f0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2a900 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2a910 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2a920 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2a930 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2a940 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2a950 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2a960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2a970 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2a980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2a990 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2a9a0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2a9b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2a9c0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2a9d0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2a9e0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2a9f0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2aa00 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2aa10 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2aa20 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2aa30 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2aa40 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2aa50 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2aa60 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2aa70 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2aa80 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2aa90 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2aaa0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2aab0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2aac0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2aad0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2aae0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2aaf0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2ab00 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2ab10 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2ab20 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2ab30 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2ab40 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2ab50 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2ab60 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2ab70 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2ab80 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2ab90 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2aba0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2abb0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2abc0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2abd0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2abe0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2abf0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2ac00 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2ac10 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2ac20 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2ac30 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2ac40 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2ac50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2ac60 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2ac70 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2ac80 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2ac90 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2aca0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2acb0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2acc0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2acd0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2ace0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2acf0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2ad00 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2ad10 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2ad20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2ad30 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2ad40 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2ad50 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2ad60 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2ad70 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2ad80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2ad90 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2ada0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2adb0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2adc0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2add0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2ade0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2adf0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2ae00 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2ae10 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2ae20 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2ae30 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2ae40 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2ae50 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2ae60 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2ae70 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2ae80 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2ae90 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2aea0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2aeb0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2aec0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2aed0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2aee0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2aef0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2af00 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2af10 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2af20 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2af30 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2af40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2af50 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2af60 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2af70 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2af80 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2af90 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2afa0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2afb0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2afc0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2afd0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2afe0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2aff0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2b000 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2b010 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2b020 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2b030 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2b040 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2b050 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2b060 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2b070 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2b080 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2b090 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2b0a0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2b0b0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2b0c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2b0d0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2b0e0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2b0f0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2b100 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2b110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2b120 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2b130 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2b140 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2b150 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2b160 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2b170 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2b180 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2b190 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2b1a0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2b1b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b1c0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2b1d0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2b1e0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2b1f0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2b200 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2b210 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2b220 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2b230 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2b240 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2b250 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2b260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2b270 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2b280 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2b290 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2b2a0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2b2b0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2b2c0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2b2d0 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2b2e0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2b2f0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2b300 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2b310 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2b320 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2b330 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2b340 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2b350 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2b360 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2b370 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2b380 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2b390 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2b3a0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2b3b0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2b3c0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2b3d0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2b3e0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2b3f0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2b400 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2b410 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2b420 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2b430 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2b440 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2b450 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2b460 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2b470 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2b480 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2b490 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2b4a0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2b4b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2b4c0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2b4d0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2b4e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2b4f0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2b500 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2b510 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2b520 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2b530 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2b540 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2b550 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b560 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2b570 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2b580 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2b590 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2b5a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2b5b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2b5c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2b5d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2b5e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2b5f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2b600 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2b610 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2b620 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2b630 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2b640 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2b650 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2b660 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2b670 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b680 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2b690 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2b6a0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2b6b0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2b6c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b6d0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2b6e0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2b6f0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2b700 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2b710 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2b720 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2b730 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2b740 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2b750 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2b760 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b770 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2b780 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b790 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2b7a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2b7b0 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2b7c0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2b7d0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2b7e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2b7f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2b800 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2b810 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2b820 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2b830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b840 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2b850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2b860 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2b870 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2b880 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2b890 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2b8a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2b8b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b8c0 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2b8d0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2b8e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b8f0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2b900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2b910 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2b920 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2b930 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2b940 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2b950 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2b960 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2b970 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2b980 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2b990 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2b9a0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2b9b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2b9c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2b9d0 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2b9e0 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2b9f0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2ba00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ba10 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2ba20 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2ba30 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2ba40 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2ba50 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2ba60 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2ba70 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2ba80 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2ba90 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2baa0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2bab0 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2bac0 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2bad0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2bae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2baf0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2bb00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2bb10 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2bb20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2bb30 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2bb40 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2bb50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2bb60 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2bb70 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2bb80 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2bb90 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2bba0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2bbb0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2bbc0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2bbd0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2bbe0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2bbf0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2bc00 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2bc10 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2bc20 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2bc30 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2bc40 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2bc50 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2bc60 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2bc70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2bc80 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2bc90 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2bca0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2bcb0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2bcc0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2bcd0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2bce0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2bcf0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2bd00 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2bd10 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2bd20 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2bd30 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2bd40 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2bd50 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2bd60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2bd70 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2bd80 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2bd90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2bda0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2bdb0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2bdc0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2bdd0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2bde0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2bdf0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2be00 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2be10 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2be20 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2be30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2be40 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2be50 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2be60 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2be70 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2be80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2be90 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2bea0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2beb0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2bec0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2bed0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2bee0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2bef0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2bf00 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2bf10 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2bf20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2bf30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2bf40 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2bf50 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2bf60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2bf70 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2bf80 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2bf90 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2bfa0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2bfb0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2bfc0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2bfd0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2bfe0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2bff0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2c000 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2c010 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2c020 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2c030 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2c040 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2c050 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2c060 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2c070 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2c080 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2c090 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2c0a0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2c0b0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2c0c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c0d0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2c0e0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2c0f0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2c100 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2c110 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2c120 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2c130 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2c140 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2c150 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2c160 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2c170 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2c180 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2c190 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2c1a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2c1b0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2c1c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2c1d0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2c1e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2c1f0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2c200 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2c210 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2c220 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2c230 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2c240 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2c250 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2c260 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2c270 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2c280 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2c290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c2a0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2c2b0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2c2c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2c2d0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2c2e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2c2f0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2c300 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2c310 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2c320 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c330 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2c340 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2c350 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2c360 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2c370 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2c380 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2c390 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2c3a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2c3b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c3c0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2c3d0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2c3e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2c3f0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2c400 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2c410 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2c420 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2c430 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2c440 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2c450 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2c460 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2c470 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2c480 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2c490 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2c4a0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2c4b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2c4c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2c4d0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2c4e0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2c4f0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2c500 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2c510 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2c520 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2c530 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2c540 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2c550 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2c560 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2c570 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2c580 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2c590 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2c5a0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2c5b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2c5c0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2c5d0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2c5e0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2c5f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c600 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2c610 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2c620 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2c630 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2c640 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2c650 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c660 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2c670 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2c680 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2c690 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2c6a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2c6b0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2c6c0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2c6d0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2c6e0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2c6f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2c700 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c710 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2c720 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2c730 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c740 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2c750 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2c760 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2c770 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2c780 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2c790 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2c7a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2c7b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2c7c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2c7d0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2c7e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2c7f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2c800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c810 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2c820 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2c830 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2c840 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2c850 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2c860 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2c870 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2c880 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2c890 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2c8a0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2c8b0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2c8c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c8d0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2c8e0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2c8f0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2c900 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2c910 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2c920 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2c930 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2c940 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2c950 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2c960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2c970 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2c980 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2c990 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2c9a0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2c9b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2c9c0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2c9d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2c9e0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2c9f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ca00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2ca10 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2ca20 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2ca30 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2ca40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ca50 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2ca60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ca70 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2ca80 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2ca90 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2caa0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2cab0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2cac0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2cad0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2cae0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2caf0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2cb00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2cb10 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2cb20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2cb30 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2cb40 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2cb50 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2cb60 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2cb70 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2cb80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2cb90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2cba0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2cbb0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2cbc0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2cbd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2cbe0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2cbf0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2cc00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2cc10 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2cc20 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2cc30 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2cc40 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2cc50 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2cc60 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2cc70 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2cc80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2cc90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2cca0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2ccb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2ccc0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2ccd0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2cce0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2ccf0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2cd00 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2cd10 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2cd20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cd30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2cd40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2cd50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2cd60 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2cd70 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2cd80 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2cd90 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2cda0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2cdb0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2cdc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2cdd0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2cde0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2cdf0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2ce00 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2ce10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2ce20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2ce30 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2ce40 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2ce50 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2ce60 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2ce70 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2ce80 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2ce90 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2cea0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2ceb0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2cec0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2ced0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2cee0 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2cef0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2cf00 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2cf10 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2cf20 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2cf30 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2cf40 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2cf50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2cf60 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2cf70 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2cf80 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2cf90 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2cfa0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2cfb0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2cfc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2cfd0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2cfe0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2cff0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2d000 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2d010 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2d020 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2d030 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2d040 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2d050 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2d060 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2d070 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2d080 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2d090 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2d0a0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2d0b0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2d0c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2d0d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2d0e0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2d0f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2d100 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2d110 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2d120 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2d130 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2d140 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2d150 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2d160 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2d170 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2d180 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2d190 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2d1a0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
2d1b0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
2d1c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2d1d0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2d1e0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2d1f0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2d200 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2d210 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2d220 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2d230 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
2d240 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2d250 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2d260 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
2d270 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2d280 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2d290 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2d2a0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
2d2b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2d2c0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2d2d0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2d2e0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2d2f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2d300 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2d310 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2d320 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2d330 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2d340 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2d350 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2d360 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
2d370 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2d380 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
2d390 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
2d3a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
2d3b0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
2d3c0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2d3d0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
2d3e0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2d3f0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2d400 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2d410 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2d420 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2d430 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2d440 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2d450 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2d460 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2d470 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2d480 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2d490 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2d4a0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2d4b0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2d4c0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2d4d0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2d4e0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2d4f0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2d500 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2d510 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2d520 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2d530 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2d540 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2d550 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2d560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d570 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2d580 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2d590 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2d5a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2d5b0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2d5c0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2d5d0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2d5e0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2d5f0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2d600 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2d610 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2d620 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2d630 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2d640 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2d650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d660 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2d670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d680 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2d690 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2d6a0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2d6b0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2d6c0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2d6d0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2d6e0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2d6f0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2d700 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2d710 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2d720 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2d730 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d740 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2d750 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2d760 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2d770 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2d780 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2d790 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2d7a0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2d7b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2d7c0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2d7d0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2d7e0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2d7f0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2d800 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2d810 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2d820 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2d830 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2d840 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2d850 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2d860 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2d870 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2d880 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2d890 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2d8a0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2d8b0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2d8c0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2d8d0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2d8e0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2d8f0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2d900 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2d910 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2d920 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2d930 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2d940 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2d950 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2d960 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2d970 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2d980 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2d990 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2d9a0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2d9b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2d9c0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2d9d0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2d9e0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2d9f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2da00 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2da10 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2da20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2da30 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2da40 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2da50 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2da60 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2da70 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2da80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2da90 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2daa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2dab0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2dac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2dad0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2dae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2daf0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2db00 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2db10 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2db20 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2db30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2db40 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2db50 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2db60 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2db70 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2db80 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2db90 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2dba0 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2dbb0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2dbc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dbd0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2dbe0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2dbf0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2dc00 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2dc10 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2dc20 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2dc30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2dc40 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2dc50 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2dc60 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2dc70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2dc80 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2dc90 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2dca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2dcb0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2dcc0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2dcd0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2dce0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2dcf0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2dd00 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2dd10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2dd20 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2dd30 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2dd40 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2dd50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2dd60 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2dd70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2dd80 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2dd90 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2dda0 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2ddb0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2ddc0 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2ddd0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2dde0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2ddf0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2de00 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2de10 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2de20 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2de30 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2de40 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2de50 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2de60 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2de70 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2de80 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2de90 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2dea0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2deb0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2dec0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2ded0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2dee0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2def0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2df00 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2df10 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2df20 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2df30 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2df40 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2df50 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2df60 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2df70 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2df80 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
2df90 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2dfa0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
2dfb0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2dfc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2dfd0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2dfe0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2dff0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2e000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
2e010 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e020 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
2e030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2e040 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2e050 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e060 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2e070 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
2e080 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e090 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2e0a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2e0b0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2e0c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2e0d0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2e0e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2e0f0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2e100 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e110 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e130 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2e140 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2e150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e160 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2e170 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2e180 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2e190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2e1a0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2e1b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2e1c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2e1d0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2e1e0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2e1f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2e200 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2e210 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2e220 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
2e230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e240 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
2e250 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2e260 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
2e270 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
2e280 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
2e290 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
2e2a0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
2e2b0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
2e2c0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
2e2d0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
2e2e0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
2e2f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2e300 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
2e310 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
2e320 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
2e330 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2e340 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
2e350 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2e360 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
2e370 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
2e380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e390 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2e3a0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2e3b0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2e3c0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
2e3d0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
2e3e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e3f0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
2e400 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
2e410 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
2e420 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
2e430 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
2e440 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2e450 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
2e460 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
2e470 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
2e480 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2e490 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
2e4a0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
2e4b0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
2e4c0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
2e4d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2e4e0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
2e4f0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
2e500 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
2e510 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2e520 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
2e530 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
2e540 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
2e550 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
2e560 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
2e570 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
2e580 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
2e590 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
2e5a0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
2e5b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e5c0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2e5d0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
2e5e0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
2e5f0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2e600 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2e610 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
2e620 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
2e630 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
2e640 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
2e650 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
2e660 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
2e670 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
2e680 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2e6a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2e6b0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2e6c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2e6d0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2e6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2e6f0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2e700 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2e710 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e720 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2e730 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2e740 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2e750 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2e760 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2e770 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2e780 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2e790 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2e7a0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2e7b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e7c0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2e7d0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2e7e0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2e7f0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2e800 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2e810 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2e820 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2e830 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2e840 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2e850 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2e860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e870 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2e880 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2e890 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2e8a0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2e8b0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2e8c0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2e8d0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2e8e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e8f0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2e900 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2e910 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2e920 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2e930 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2e940 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2e950 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2e960 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2e970 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2e980 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2e990 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2e9a0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2e9b0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2e9c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e9d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2e9e0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2e9f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2ea00 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2ea10 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2ea20 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2ea30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2ea40 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2ea50 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2ea60 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2ea70 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2ea80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ea90 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2eaa0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2eab0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
2eac0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2ead0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2eae0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2eaf0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2eb00 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2eb10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2eb20 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2eb30 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2eb40 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2eb50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2eb60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2eb70 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2eb80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2eb90 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2eba0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2ebb0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2ebc0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2ebd0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2ebe0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2ebf0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2ec00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2ec10 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2ec20 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2ec30 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2ec40 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2ec50 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2ec60 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2ec70 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
2ec80 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
2ec90 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
2eca0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
2ecb0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
2ecc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2ecd0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
2ece0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
2ecf0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
2ed00 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
2ed10 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
2ed20 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2ed30 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
2ed40 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2ed50 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2ed60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2ed70 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2ed80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2ed90 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2eda0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2edb0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
2edc0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2edd0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2ede0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2edf0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
2ee00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ee10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2ee20 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
2ee30 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
2ee40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
2ee50 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
2ee60 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2ee70 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2ee80 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2ee90 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2eea0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2eeb0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
2eec0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2eed0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2eee0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
2eef0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
2ef00 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
2ef10 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2ef20 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
2ef30 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
2ef40 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
2ef50 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
2ef60 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
2ef70 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
2ef80 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
2ef90 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2efa0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2efb0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2efc0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2efd0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
2efe0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2eff0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
2f000 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
2f010 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2f020 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2f030 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f040 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2f050 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
2f060 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
2f070 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
2f080 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2f090 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
2f0a0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2f0b0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
2f0c0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
2f0d0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
2f0e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2f0f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2f100 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
2f110 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
2f120 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
2f130 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2f140 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
2f150 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
2f160 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2f170 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
2f180 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2f190 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2f1a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2f1b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2f1c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2f1d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2f1e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2f1f0 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
2f200 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2f210 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
2f220 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
2f230 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2f240 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2f250 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2f260 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2f270 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2f280 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2f290 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2f2a0 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
2f2b0 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
2f2c0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2f2d0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
2f2e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f2f0 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
2f300 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
2f310 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2f320 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
2f330 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
2f340 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
2f350 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2f360 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f370 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2f380 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2f390 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2f3a0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2f3b0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2f3c0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2f3d0 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2f3e0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2f3f0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2f400 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2f410 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2f420 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2f430 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2f440 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2f450 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2f460 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2f470 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
2f480 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2f490 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2f4a0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2f4b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2f4c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2f4d0 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2f4e0 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2f4f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2f500 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
2f510 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
2f520 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
2f530 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2f540 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2f550 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2f560 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2f570 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2f580 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2f590 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2f5a0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
2f5b0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2f5c0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2f5d0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2f5e0 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2f5f0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
2f600 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
2f610 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2f620 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2f630 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2f640 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
2f650 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2f660 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2f670 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2f680 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2f690 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
2f6a0 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
2f6b0 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
2f6c0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
2f6d0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
2f6e0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
2f6f0 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
2f700 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
2f710 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
2f720 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
2f730 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
2f740 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f750 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f760 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
2f770 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
2f780 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
2f790 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2f7a0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
2f7b0 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
2f7c0 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
2f7d0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
2f7e0 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
2f7f0 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
2f800 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
2f810 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2f820 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
2f830 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
2f840 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
2f850 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
2f860 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2f870 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f880 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
2f890 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
2f8a0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
2f8b0 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
2f8c0 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
2f8d0 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
2f8e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2f8f0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
2f900 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
2f910 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
2f920 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
2f930 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
2f940 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f950 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2f960 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
2f970 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2f980 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
2f990 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f9a0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
2f9b0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
2f9c0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2f9d0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
2f9e0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
2f9f0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
2fa00 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
2fa10 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2fa20 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
2fa30 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
2fa40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
2fa50 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
2fa60 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
2fa70 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
2fa80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2fa90 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
2faa0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2fab0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
2fac0 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
2fad0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
2fae0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
2faf0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
2fb00 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
2fb10 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
2fb20 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
2fb30 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
2fb40 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2fb50 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
2fb60 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
2fb70 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
2fb80 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
2fb90 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2fba0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
2fbb0 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
2fbc0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2fbd0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2fbe0 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
2fbf0 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
2fc00 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
2fc10 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
2fc20 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2fc30 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2fc40 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
2fc50 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
2fc60 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
2fc70 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2fc80 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2fc90 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2fca0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fcb0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
2fcc0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
2fcd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fce0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2fcf0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
2fd00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
2fd10 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
2fd20 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
2fd30 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
2fd40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fd50 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
2fd60 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2fd70 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2fd80 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
2fd90 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2fda0 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
2fdb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fdc0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2fdd0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2fde0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2fdf0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2fe00 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2fe10 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2fe20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2fe30 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fe40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2fe50 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2fe60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fe70 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fe80 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fe90 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2fea0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2feb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fec0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2fed0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2fee0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2fef0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2ff00 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2ff10 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2ff20 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2ff30 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2ff40 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2ff50 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2ff60 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2ff70 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2ff80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2ff90 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2ffa0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ffb0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2ffc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ffd0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
2ffe0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2fff0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
30000 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
30010 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
30020 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
30030 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
30040 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
30050 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
30060 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
30070 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
30080 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30090 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
300a0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
300b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
300c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
300d0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
300e0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
300f0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
30100 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
30110 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
30120 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
30130 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
30140 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
30150 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
30160 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
30170 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
30180 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
30190 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
301a0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
301b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
301c0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
301d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
301e0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
301f0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
30200 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
30210 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
30220 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
30230 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30240 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
30250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
30260 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
30270 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
30280 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
30290 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
302a0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
302b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
302c0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
302d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
302e0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
302f0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
30300 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
30310 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
30320 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
30330 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
30340 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
30350 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
30360 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
30370 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
30380 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
30390 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
303a0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
303b0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
303c0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
303d0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
303e0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
303f0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
30400 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
30410 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
30420 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
30430 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
30440 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
30450 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
30460 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30470 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
30480 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
30490 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
304a0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
304b0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
304c0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
304d0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
304e0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
304f0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
30500 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30510 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
30520 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
30530 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
30540 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
30550 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
30560 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
30570 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
30580 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
30590 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
305a0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
305b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
305c0 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
305d0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
305e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
305f0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
30600 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
30610 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
30620 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
30630 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
30640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
30650 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
30660 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
30670 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
30680 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
30690 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
306a0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
306b0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
306c0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
306d0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
306e0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
306f0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
30700 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
30710 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
30720 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
30730 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30740 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
30750 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
30760 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
30770 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
30780 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
30790 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
307a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
307b0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
307c0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
307d0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
307e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
307f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30800 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
30810 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
30820 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
30830 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
30840 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30850 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
30860 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
30870 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
30880 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
30890 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
308a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
308b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
308c0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
308d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
308e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
308f0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
30900 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
30910 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
30920 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30930 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
30940 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
30950 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
30960 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
30970 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
30980 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
30990 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
309a0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
309b0 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
309c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
309d0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
309e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
309f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
30a00 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
30a10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
30a20 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
30a30 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
30a40 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
30a50 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
30a60 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
30a70 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
30a80 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
30a90 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
30aa0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
30ab0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
30ac0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
30ad0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
30ae0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
30af0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
30b00 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
30b10 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
30b20 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
30b30 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
30b40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
30b50 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
30b60 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
30b70 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
30b80 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
30b90 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
30ba0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
30bb0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
30bc0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
30bd0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
30be0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
30bf0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
30c00 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
30c10 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
30c20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
30c30 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
30c40 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
30c50 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
30c60 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
30c70 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
30c80 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
30c90 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
30ca0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
30cb0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
30cc0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
30cd0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
30ce0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
30cf0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
30d00 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
30d10 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
30d20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
30d30 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
30d40 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
30d50 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
30d60 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
30d70 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
30d80 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
30d90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30da0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
30db0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30dc0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
30dd0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
30de0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
30df0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
30e00 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
30e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30e20 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
30e30 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
30e40 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
30e50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
30e60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
30e70 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
30e80 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
30e90 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
30ea0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30eb0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
30ec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30ed0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
30ee0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
30ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
30f00 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
30f10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
30f20 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
30f30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
30f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30f50 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
30f60 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
30f70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
30f80 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
30f90 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
30fa0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
30fb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
30fc0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
30fd0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
30fe0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
30ff0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
31000 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
31010 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
31020 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
31030 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
31040 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
31050 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
31060 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31070 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
31080 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31090 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
310a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
310b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
310c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
310d0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
310e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
310f0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
31100 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
31110 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
31120 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
31130 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
31140 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
31150 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
31160 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
31170 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
31180 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
31190 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
311a0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
311b0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
311c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
311d0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
311e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
311f0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
31200 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
31210 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
31220 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
31230 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
31240 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
31250 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
31260 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
31270 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
31280 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
31290 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
312a0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
312b0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
312c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
312d0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
312e0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
312f0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
31300 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
31310 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
31320 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
31330 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
31340 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
31350 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
31360 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
31370 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
31380 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
31390 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
313a0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
313b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
313c0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
313d0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
313e0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
313f0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
31400 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
31410 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
31420 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
31430 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
31440 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
31450 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
31460 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
31470 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
31480 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31490 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
314a0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
314b0 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
314c0 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
314d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
314e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
314f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
31500 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
31510 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
31520 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
31530 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
31540 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
31550 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
31560 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
31570 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
31580 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
31590 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
315a0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
315b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
315c0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
315d0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
315e0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
315f0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
31600 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
31610 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
31620 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
31630 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
31640 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31650 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
31660 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
31670 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
31680 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
31690 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
316a0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
316b0 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
316c0 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
316d0 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
316e0 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
316f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
31700 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31710 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
31720 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
31730 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
31740 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
31750 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
31760 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
31770 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
31780 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
31790 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
317a0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
317b0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
317c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
317d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
317e0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
317f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
31800 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
31810 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
31820 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
31830 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
31840 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
31850 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
31860 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
31870 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
31880 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
31890 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
318a0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
318b0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
318c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
318d0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
318e0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
318f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
31900 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
31910 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
31920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31930 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
31940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
31950 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
31960 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
31970 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
31980 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
31990 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
319a0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
319b0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
319c0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
319d0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
319e0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
319f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31a00 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
31a10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
31a20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
31a30 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
31a40 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
31a50 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
31a60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
31a70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
31a80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
31a90 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
31aa0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
31ab0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
31ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31ad0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
31ae0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
31af0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
31b00 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
31b10 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
31b20 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
31b30 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
31b40 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
31b50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
31b60 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
31b70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
31b80 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
31b90 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
31ba0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
31bb0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
31bc0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
31bd0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
31be0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31bf0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
31c00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31c10 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
31c20 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
31c30 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
31c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31c50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31c60 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
31c70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
31c80 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
31c90 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
31ca0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
31cb0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
31cc0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
31cd0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
31ce0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
31cf0 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
31d00 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
31d10 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
31d20 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
31d30 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
31d40 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
31d50 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
31d60 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
31d70 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
31d80 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
31d90 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
31da0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
31db0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
31dc0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
31dd0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
31de0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
31df0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
31e00 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
31e10 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
31e20 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
31e30 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
31e40 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
31e50 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
31e60 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
31e70 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
31e80 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
31e90 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
31ea0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
31eb0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
31ec0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
31ed0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
31ee0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
31ef0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
31f00 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
31f10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
31f20 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
31f30 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
31f40 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
31f50 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
31f60 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
31f70 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
31f80 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
31f90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31fa0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
31fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
31fd0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
31fe0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
31ff0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32000 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
32010 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
32020 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
32030 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32040 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32050 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
32060 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
32070 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
32080 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
32090 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
320a0 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
320b0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
320c0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
320d0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
320e0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
320f0 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
32100 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
32110 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
32120 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
32130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32140 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32150 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
32160 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
32170 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
32180 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
32190 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
321a0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
321b0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
321c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
321d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
321e0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
321f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
32200 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
32210 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
32220 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
32230 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
32240 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
32250 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
32260 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
32270 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
32280 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
32290 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
322a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
322b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
322c0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
322d0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
322e0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
322f0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
32300 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
32310 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32320 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
32330 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
32340 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
32350 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
32360 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
32370 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
32380 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
32390 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
323a0 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
323b0 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
323c0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
323d0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
323e0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
323f0 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
32400 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
32410 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
32420 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
32430 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
32440 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
32450 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
32460 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
32470 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
32480 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
32490 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
324a0 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
324b0 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
324c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
324d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
324e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
324f0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
32500 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32510 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
32520 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
32530 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
32540 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32550 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
32560 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
32570 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32580 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
32590 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
325a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
325b0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
325c0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
325d0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
325e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
325f0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
32600 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
32610 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
32620 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
32630 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
32640 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
32650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32660 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
32670 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
32680 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
32690 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
326a0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
326b0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
326c0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
326d0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
326e0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
326f0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
32700 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
32710 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
32720 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
32730 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
32740 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
32750 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
32760 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
32770 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
32780 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
32790 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
327a0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
327b0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
327c0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
327d0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
327e0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
327f0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
32800 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
32810 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
32820 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
32830 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
32840 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
32850 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
32860 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
32870 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
32880 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
32890 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
328a0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
328b0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
328c0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
328d0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
328e0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
328f0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
32900 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32910 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
32920 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
32930 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
32940 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
32950 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
32960 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
32970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
32980 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
32990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
329a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
329b0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
329c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
329d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
329e0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
329f0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
32a00 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
32a10 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
32a20 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
32a30 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
32a40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
32a50 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
32a60 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
32a70 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
32a80 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
32a90 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
32aa0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
32ab0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
32ad0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32ae0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
32af0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
32b00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32b10 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
32b20 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
32b30 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
32b40 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
32b50 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
32b60 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
32b70 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
32b80 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
32b90 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
32ba0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32bb0 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
32bc0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
32bd0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
32be0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32bf0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32c00 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
32c10 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
32c20 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
32c30 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
32c40 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
32c50 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
32c60 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
32c70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32c80 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
32c90 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
32ca0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
32cb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32cc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
32cd0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
32ce0 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
32cf0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
32d00 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
32d10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32d20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
32d30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32d40 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
32d50 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
32d60 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
32d70 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
32d80 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
32d90 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
32da0 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
32db0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
32dc0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
32dd0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
32de0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
32df0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32e00 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
32e10 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
32e20 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
32e30 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
32e40 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
32e50 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
32e60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32e70 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
32e80 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
32e90 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
32ea0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
32eb0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
32ec0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
32ed0 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
32ee0 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
32ef0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32f00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32f10 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
32f20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32f30 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
32f40 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
32f50 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
32f60 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
32f70 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
32f80 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
32f90 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
32fa0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
32fb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
32fc0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
32fd0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
32fe0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
32ff0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
33000 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
33010 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
33020 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
33030 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
33040 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
33050 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
33060 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33070 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
33080 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33090 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
330a0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
330b0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
330c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
330d0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
330e0 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
330f0 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
33100 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
33110 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
33120 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
33130 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
33140 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
33150 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33160 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
33170 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
33180 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
33190 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
331a0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
331b0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
331c0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
331d0 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
331e0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
331f0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
33200 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
33210 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
33220 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
33230 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
33240 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
33250 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
33260 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
33270 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
33280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33290 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ror_toobig() int
332a0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
332b0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
332c0 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
332d0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
332e0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
332f0 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
33300 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
33310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33320 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  rror_nomem() int
33330 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
33340 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
33350 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
33360 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
33370 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
33380 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
33390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
333a0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
333b0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
333c0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
333d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
333e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
333f0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
33400 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
33410 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
33420 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
33430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33440 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
33450 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33460 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
33470 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
33480 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33490 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
334a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
334b0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
334c0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
334d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
334e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
334f0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
33500 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33510 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
33520 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
33530 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33540 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
33550 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33560 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
33570 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33580 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
33590 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
335a0 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
335b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
335c0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
335d0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
335e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
335f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33600 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33610 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
33620 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
33630 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
33640 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
33650 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
33660 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
33670 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
33680 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
33690 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
336a0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
336b0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
336c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
336d0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
336e0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
336f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33700 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33710 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
33720 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
33730 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33740 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
33750 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
33760 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
33770 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
33780 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
33790 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
337a0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
337b0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
337c0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
337d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
337e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
337f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
33800 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
33810 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
33820 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
33830 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
33840 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
33850 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33860 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
33870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33880 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
33890 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
338a0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
338b0 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
338c0 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
338d0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
338e0 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
338f0 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
33900 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
33910 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
33920 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
33930 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
33940 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
33950 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
33960 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
33970 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
33980 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
33990 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
339a0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
339b0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
339c0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
339d0 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
339e0 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
339f0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
33a00 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
33a10 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
33a20 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
33a30 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
33a40 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
33a50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
33a60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33a70 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33a80 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
33a90 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
33aa0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
33ab0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
33ac0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
33ad0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
33ae0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
33af0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
33b00 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
33b10 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
33b20 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
33b30 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
33b40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
33b50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33b60 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
33b70 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
33b80 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
33b90 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
33ba0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
33bb0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
33bc0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
33bd0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
33be0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
33bf0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
33c00 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
33c10 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
33c20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
33c30 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
33c40 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
33c50 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
33c60 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
33c70 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
33c80 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
33c90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
33ca0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33cb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
33cc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
33cd0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
33ce0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
33cf0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
33d00 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
33d10 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
33d20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
33d30 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
33d40 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
33d50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
33d60 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
33d70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
33d90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
33da0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
33db0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
33dc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33dd0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
33de0 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
33df0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33e00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
33e10 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
33e20 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
33e30 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
33e40 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
33e50 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
33e60 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
33e70 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
33e80 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
33e90 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
33ea0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
33eb0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
33ec0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
33ed0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
33ee0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
33ef0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
33f00 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
33f10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33f20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
33f30 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
33f40 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
33f50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33f60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33f70 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
33f80 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
33f90 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
33fa0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
33fb0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
33fc0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
33fd0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
33fe0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
33ff0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
34000 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
34010 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
34020 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
34030 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34040 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
34050 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
34060 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
34070 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
34080 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
34090 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
340a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
340b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
340c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
340d0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
340e0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
340f0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
34100 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34110 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
34120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34130 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
34140 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
34150 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
34160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34170 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
34180 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
34190 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
341a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
341b0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
341c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
341d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
341e0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
341f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34200 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34210 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
34220 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
34230 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
34240 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34250 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
34260 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
34270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34280 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
34290 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
342a0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
342b0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
342c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
342d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
342e0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
342f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34300 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
34310 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34320 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34330 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
34340 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34350 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
34360 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34370 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34380 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
34390 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
343a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
343b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
343c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
343d0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
343e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
343f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34400 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
34410 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34420 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
34430 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
34440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
34450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34460 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
34470 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34480 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
34490 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
344a0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
344b0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
344c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
344d0 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
344e0 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
344f0 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
34500 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
34510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
34520 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
34530 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
34540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
34550 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
34560 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
34570 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
34580 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34590 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
345a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
345b0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
345c0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
345d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
345e0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
345f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
34600 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
34610 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
34620 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
34630 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
34640 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
34650 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
34660 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
34670 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
34680 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
34690 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
346a0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
346b0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
346c0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
346d0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
346e0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
346f0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
34700 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
34710 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
34720 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
34730 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
34740 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
34750 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
34760 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
34770 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
34780 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
34790 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
347a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
347b0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
347c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
347d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
347e0 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
347f0 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
34800 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
34810 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
34820 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
34830 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34840 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
34850 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
34860 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
34870 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
34880 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
34890 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
348a0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
348b0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
348c0 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
348d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
348e0 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
348f0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
34900 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
34910 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
34920 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34930 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
34940 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
34950 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
34960 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
34970 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
34980 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
34990 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
349a0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
349b0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
349c0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
349d0 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
349e0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
349f0 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
34a00 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
34a10 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
34a20 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
34a30 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
34a40 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
34a50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
34a60 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
34a70 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
34a80 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
34a90 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
34aa0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
34ab0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
34ac0 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
34ad0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
34ae0 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
34af0 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
34b00 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
34b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
34b20 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34b30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
34b40 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
34b50 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
34b60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
34b70 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
34b80 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
34b90 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
34ba0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
34bb0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
34bc0 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
34bd0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
34be0 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
34bf0 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
34c00 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
34c10 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
34c20 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
34c30 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
34c40 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
34c50 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
34c60 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
34c70 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
34c80 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
34c90 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
34ca0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
34cb0 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
34cc0 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
34cd0 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
34ce0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
34cf0 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
34d00 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
34d10 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
34d20 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
34d30 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
34d40 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
34d50 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
34d60 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
34d70 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
34d80 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
34d90 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
34da0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
34db0 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
34dc0 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
34dd0 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
34de0 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
34df0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
34e00 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
34e10 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
34e20 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
34e30 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
34e40 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
34e50 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
34e60 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
34e70 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
34e80 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
34e90 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
34ea0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
34eb0 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
34ec0 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
34ed0 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
34ee0 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
34ef0 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
34f00 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
34f10 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
34f20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
34f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34f40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34f50 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
34f60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34f70 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
34f80 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
34f90 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
34fa0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
34fb0 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
34fc0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
34fd0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34fe0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
34ff0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35000 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
35010 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
35020 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
35030 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
35040 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
35050 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
35060 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
35070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35080 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
35090 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
350a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
350b0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
350c0 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
350d0 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
350e0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
350f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
35100 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
35110 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
35120 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
35130 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35140 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
35150 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
35160 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
35170 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
35180 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
35190 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
351a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
351b0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
351c0 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
351d0 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
351e0 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
351f0 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
35200 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
35210 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
35220 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
35230 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
35240 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
35250 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
35260 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
35270 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
35280 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
35290 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
352a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
352b0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
352c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
352d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
352e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
352f0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
35300 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35310 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
35320 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35330 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
35340 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
35350 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
35360 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
35370 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
35380 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
35390 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
353a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
353b0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
353c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
353d0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
353e0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
353f0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
35400 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
35410 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
35420 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
35430 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
35440 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
35450 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35460 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
35470 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
35480 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
35490 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
354a0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
354b0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
354c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
354d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
354e0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
354f0 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
35500 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
35510 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
35520 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
35530 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
35540 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
35550 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
35560 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
35570 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
35580 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
35590 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
355a0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
355b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
355c0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
355d0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
355e0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
355f0 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
35600 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
35610 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
35620 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
35630 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
35640 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
35650 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
35660 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
35670 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
35680 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
35690 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
356a0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
356b0 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
356c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
356d0 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
356e0 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
356f0 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
35700 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
35710 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
35720 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
35730 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
35740 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
35750 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
35760 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
35770 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
35780 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
35790 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
357a0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
357b0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
357c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
357d0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
357e0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
357f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
35800 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
35810 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
35820 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
35830 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
35840 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
35850 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
35860 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
35870 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
35880 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
35890 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
358a0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
358b0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
358c0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
358d0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
358e0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
358f0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
35900 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
35910 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
35920 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
35930 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
35940 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
35950 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
35960 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
35970 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
35980 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
35990 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
359a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
359b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
359c0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
359d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
359e0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
359f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
35a00 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
35a10 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
35a20 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
35a30 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
35a40 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
35a50 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
35a60 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35a70 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
35a80 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
35a90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
35aa0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
35ab0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
35ac0 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
35ad0 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
35ae0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
35af0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
35b00 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
35b10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
35b20 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
35b30 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
35b40 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
35b50 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
35b60 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
35b70 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
35b80 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
35b90 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
35ba0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
35bb0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
35bc0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
35bd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
35be0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
35bf0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
35c00 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
35c10 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
35c20 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
35c30 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
35c40 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
35c50 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
35c60 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
35c70 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
35c80 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
35c90 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
35ca0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
35cb0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
35cc0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
35cd0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
35ce0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
35cf0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
35d00 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
35d10 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
35d20 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
35d30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35d40 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
35d50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
35d60 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
35d70 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
35d80 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
35d90 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
35da0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
35db0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
35dc0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
35dd0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
35de0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
35df0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
35e00 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
35e10 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
35e20 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
35e30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
35e40 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
35e50 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
35e60 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
35e70 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
35e80 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
35e90 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
35ea0 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
35eb0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
35ec0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
35ed0 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
35ee0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
35ef0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
35f00 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
35f10 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
35f20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
35f30 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
35f40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
35f50 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
35f60 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
35f70 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
35f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35f90 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
35fa0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
35fb0 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
35fc0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
35fd0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
35fe0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
35ff0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
36000 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
36010 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
36020 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
36030 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
36040 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
36050 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
36060 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
36070 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
36080 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
36090 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
360a0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
360b0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
360c0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
360d0 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
360e0 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
360f0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
36100 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
36110 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
36120 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
36130 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
36140 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
36150 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
36160 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
36170 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
36180 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
36190 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
361a0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
361b0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
361c0 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
361d0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
361e0 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
361f0 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
36200 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
36210 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
36220 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
36230 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
36240 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
36250 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
36260 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
36270 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
36280 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20  agraphs..*/.int 
36290 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
362a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
362b0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
362c0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
362d0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
362e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
362f0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
36300 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
36310 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
36320 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
36330 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
36340 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
36350 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
36360 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
36370 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
36380 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
36390 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
363a0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
363b0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
363c0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
363d0 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
363e0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
363f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
36400 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
36410 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
36420 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
36430 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
36440 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
36450 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
36460 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
36470 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
36480 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
36490 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
364a0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
364b0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
364c0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
364d0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
364e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
364f0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
36500 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
36510 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
36520 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
36530 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
36540 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
36550 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
36560 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
36570 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
36580 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
36590 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
365a0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
365b0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
365c0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
365d0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
365e0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
365f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
36600 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
36610 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
36620 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36630 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
36640 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
36650 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36660 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36670 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
36680 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
36690 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
366a0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
366b0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
366c0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
366d0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
366e0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
366f0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
36700 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
36710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
36720 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
36730 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
36740 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
36750 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36760 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
36770 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
36780 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
36790 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
367a0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
367b0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
367c0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
367d0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
367e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
367f0 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
36800 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
36810 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
36820 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
36830 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
36840 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
36850 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
36860 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
36870 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
36880 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
36890 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
368a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
368b0 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  n] or [sqlite3_o
368c0 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77  pen_v2].  Otherw
368d0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
368e0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
368f0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
36900 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
36910 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65   may fail.  Here
36920 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c   is an.** exampl
36930 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74  e of how to do t
36940 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69  his using C++ wi
36950 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52  th the Windows R
36960 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62  untime:.**.** <b
36970 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
36980 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68  ** LPCWSTR zPath
36990 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72   = Windows::Stor
369a0 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e  age::Application
369b0 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a  Data::Current->.
369c0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65  ** &nbsp;     Te
369d0 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50  mporaryFolder->P
369e0 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20  ath->Data();.** 
369f0 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39  char zPathBuf&#9
36a00 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23  1;MAX_PATH + 1&#
36a10 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a  93;;.** memset(z
36a20 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65  PathBuf, 0, size
36a30 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a  of(zPathBuf));.*
36a40 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74  * WideCharToMult
36a50 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30  iByte(CP_UTF8, 0
36a60 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61  , zPath, -1, zPa
36a70 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50  thBuf, sizeof(zP
36a80 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73  athBuf),.** &nbs
36a90 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c  p;     NULL, NUL
36aa0 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  L);.** sqlite3_t
36ab0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20  emp_directory = 
36ac0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
36ad0 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b  "%s", zPathBuf);
36ae0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
36af0 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54  kquote>.*/.SQLIT
36b00 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
36b10 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
36b20 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
36b30 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
36b40 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
36b50 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  ng Database File
36b60 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
36b70 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
36b80 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
36b90 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
36ba0 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
36bb0 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
36bc0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
36bd0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74  y), then all dat
36be0 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73  abase files.** s
36bf0 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20  pecified with a 
36c00 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
36c10 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72  e and created or
36c20 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20   accessed by.** 
36c30 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
36c40 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e  g a built-in win
36c50 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66  dows [sqlite3_vf
36c60 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65  s | VFS] will be
36c70 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62   assumed.** to b
36c80 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68  e relative to th
36c90 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
36ca0 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
36cb0 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e is a NULL.** p
36cc0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
36cd0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
36ce0 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69   all database fi
36cf0 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  les specified.**
36d00 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65   with a relative
36d10 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65   pathname are re
36d20 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75  lative to the cu
36d30 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a  rrent directory.
36d40 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65  ** for the proce
36d50 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69  ss.  Only the wi
36d60 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20  ndows VFS makes 
36d70 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62  use of this glob
36d80 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20  al.** variable; 
36d90 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79  it is ignored by
36da0 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a   the unix VFS..*
36db0 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68  *.** Changing th
36dc0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  e value of this 
36dd0 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61  variable while a
36de0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36df0 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20  tion is.** open 
36e00 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20  can result in a 
36e10 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65  corrupt database
36e20 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
36e30 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
36e40 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
36e50 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
36e60 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
36e70 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
36e80 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
36e90 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
36ea0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
36eb0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
36ec0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
36ed0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
36ee0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
36ef0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
36f00 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
36f10 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
36f20 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
36f30 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
36f40 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
36f50 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
36f60 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
36f70 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
36f80 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
36f90 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
36fa0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
36fb0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
36fc0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
36fd0 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74  ** ^The [data_st
36fe0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
36ff0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
37000 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
37010 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
37020 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
37030 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
37040 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37050 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
37060 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74  .** the [data_st
37070 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37080 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
37090 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
370a0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
370b0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
370c0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
370d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
370e0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
370f0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
37100 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
37110 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
37120 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
37130 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
37140 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
37150 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
37160 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
37170 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
37180 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
37190 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
371a0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
371b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
371c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
371d0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
371e0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74   of the [data_st
371f0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37200 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
37210 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
37220 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
37230 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72  sqlite3_data_dir
37240 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
37250 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
37260 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
37270 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
37280 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
37290 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
372a0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
372b0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
372c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
372d0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
372e0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
372f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37300 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
37310 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
37320 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
37330 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
37340 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
37350 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
37360 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
37370 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
37380 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
37390 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
373a0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
373b0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
373c0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
373d0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
373e0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
373f0 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
37400 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
37410 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
37420 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
37430 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
37440 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
37450 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
37460 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
37470 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
37480 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
37490 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
374a0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
374b0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
374c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
374d0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
374e0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
374f0 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
37500 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
37510 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
37520 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
37530 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
37540 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
37550 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
37560 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
37570 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
37580 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
37590 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
375a0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
375b0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
375c0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
375d0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
375e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
375f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
37600 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
37610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37620 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
37630 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
37640 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
37650 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
37660 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
37670 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
37680 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
37690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
376a0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
376b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
376c0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
376d0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
376e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
376f0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
37700 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
37710 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
37720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
37730 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
37740 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
37750 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
37760 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
37770 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
37780 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
37790 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
377a0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
377b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
377c0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
377d0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
377e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
377f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37800 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69  F: Return The Fi
37810 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74  lename For A Dat
37820 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
37830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37840 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
37850 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
37860 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
37870 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a   to a filename.*
37880 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
37890 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20  h database N of 
378a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e  connection D.  ^
378b0 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  The main databas
378c0 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68  e file.** has th
378d0 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20  e name "main".  
378e0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61  If there is no a
378f0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
37900 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61   N on the databa
37910 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
37920 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61   D, or if databa
37930 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72  se N is a tempor
37940 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79  ary or in-memory
37950 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a   database, then.
37960 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
37970 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
37980 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61  *.** ^The filena
37990 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  me returned by t
379a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
379b0 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68  the output of th
379c0 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61  e.** xFullPathna
379d0 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  me method of the
379e0 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68   [VFS].  ^In oth
379f0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69  er words, the fi
37a00 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62  lename.** will b
37a10 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  e an absolute pa
37a20 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20  thname, even if 
37a30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65  the filename use
37a40 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65  d.** to open the
37a50 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e   database origin
37a60 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f  ally was a URI o
37a70 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  r relative pathn
37a80 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ame..*/.const ch
37a90 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66  ar *sqlite3_db_f
37aa0 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20  ilename(sqlite3 
37ab0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
37ac0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
37ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
37ae0 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 62  rmine if a datab
37af0 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79  ase is read-only
37b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37b10 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28  te3_db_readonly(
37b20 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
37b30 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 20  eturns 1 if the 
37b40 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66  database N.** of
37b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73   connection D is
37b60 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66   read-only, 0 if
37b70 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69 74   it is read/writ
37b80 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73  e, or -1 if N is
37b90 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65   not.** the name
37ba0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 6f   of a database o
37bb0 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  n connection D..
37bc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
37bd0 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  b_readonly(sqlit
37be0 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
37bf0 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
37c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37c10 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
37c20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
37c30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
37c40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37c50 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
37c60 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
37c70 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
37c80 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
37c90 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
37ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37cb0 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
37cc0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
37cd0 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
37ce0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
37cf0 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
37d00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37d10 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
37d20 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
37d30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
37d40 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
37d50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
37d60 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
37d70 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
37d80 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
37d90 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
37da0 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
37db0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
37dc0 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
37dd0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
37de0 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
37df0 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
37e00 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
37e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
37e20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
37e30 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
37e40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
37e50 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
37e60 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
37e70 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
37e80 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
37e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37ea0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
37eb0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
37ec0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
37ed0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37ee0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
37ef0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
37f00 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
37f10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
37f20 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
37f30 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
37f40 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
37f50 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
37f60 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
37f70 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
37f80 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
37f90 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
37fa0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
37fb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
37fc0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
37fd0 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
37fe0 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
37ff0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
38000 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
38010 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
38020 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
38030 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
38040 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
38050 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
38060 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
38070 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
38080 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
38090 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
380a0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
380b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
380c0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
380d0 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
380e0 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
380f0 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
38100 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
38110 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
38120 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
38130 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
38140 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
38150 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
38160 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
38170 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
38180 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
38190 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
381a0 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
381b0 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
381c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
381d0 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
381e0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
381f0 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
38200 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
38210 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
38220 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38230 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
38240 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
38250 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
38260 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
38270 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64  * The commit and
38280 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
38290 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74  allbacks are not
382a0 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54   reentrant..** T
382b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
382c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
382d0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
382e0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
382f0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
38300 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
38310 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
38320 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
38330 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
38340 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
38350 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
38360 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
38370 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
38380 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
38390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
383a0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
383b0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
383c0 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
383d0 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
383e0 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
383f0 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  hat running any 
38400 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d  other SQL statem
38410 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ents, including 
38420 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
38430 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20  s,.** or merely 
38440 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
38450 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
38460 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
38470 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  ()] will modify.
38480 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
38490 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
384a0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
384b0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
384c0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
384d0 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
384e0 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
384f0 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
38500 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
38510 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
38520 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
38530 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
38540 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
38550 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
38560 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
38570 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
38580 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
38590 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
385a0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
385b0 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
385c0 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
385d0 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
385e0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
385f0 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
38600 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
38610 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
38620 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
38630 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
38640 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
38650 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
38660 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
38670 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
38680 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
38690 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
386a0 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
386b0 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
386c0 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
386d0 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
386e0 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
386f0 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
38700 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
38710 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
38720 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
38730 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
38740 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
38750 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
38760 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
38770 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
38780 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
38790 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
387a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
387b0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
387c0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
387d0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
387e0 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
387f0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
38800 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
38810 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
38820 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
38830 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
38840 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  ba