/ Hex Artifact Content
Login

Artifact 42c69ea00dfcce84394d6ce0d8dac7bb3d2ecff2:


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 52 4f 57 20  fine SQLITE_ROW 
4a60: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4a70: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4a80: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4a90: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4aa0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4ab0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4ac0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ad0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4ae0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4af0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4b00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4b10: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4b20: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4b30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4b40: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4b50: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4b60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b80: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
4b90: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4ba0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4bb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4bc0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4bd0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4be0: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4bf0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4c00: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4c10: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4c20: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4c30: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4c40: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4c50: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4c60: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4c70: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4c80: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4c90: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4ca0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4cb0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4cc0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4cd0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4ce0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4cf0: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4d00: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4d10: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4d20: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4d30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4d40: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4d50: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4d60: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4d70: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
4d80: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4d90: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4da0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
4db0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
4dc0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
4dd0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4de0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4df0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4e00: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4e10: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4e20: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4e30: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4e40: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4e50: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4e60: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4e70: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4e80: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4e90: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4ea0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4eb0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ec0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4ed0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4ee0: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4ef0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4f00: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4f10: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4f20: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4f30: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
4f40: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
4f50: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
4f60: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
4f70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f80: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4fb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4fc0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4fd0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4fe0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4ff0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
5000: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5010: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5020: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5080: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
51e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51f0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
5200: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5210: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5230: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5240: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5250: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5270: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5290: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
52a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52b0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
52c0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
52d0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
52e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52f0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
5300: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5310: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5330: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
5340: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5350: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53b0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
53c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53d0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53f0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
5400: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5410: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5430: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5450: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5470: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5480: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5490: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54b0: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
54c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54d0: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54f0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
5500: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5510: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5530: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
5540: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5550: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5570: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5580: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5590: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
55b0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
55d0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5600: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5610: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5620: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5630: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5640: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5650: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5680: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5690: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56a0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
56b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
56c0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56d0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56e0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5700: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5710: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5720: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5740: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5750: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5760: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5780: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5790: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
57a0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
57c0: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
57e0: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5800: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5820: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5840: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5850: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5860: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5880: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5890: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
58a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
58b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58d0: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
58e0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58f0: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
5900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5910: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
5920: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5930: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
5940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5950: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
5960: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
5970: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5980: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
59a0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
59b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59c0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
59d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59e0: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
59f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a00: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
5a10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a20: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
5a30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a40: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5a50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5a60: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5a70: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5a80: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5a90: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5aa0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5ab0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5ac0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ad0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5ae0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5af0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5b00: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5b10: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5b20: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5b30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b40: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5b50: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5b60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5b70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5b80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b90: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5ba0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5bb0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5bc0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5be0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5bf0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5c00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5c10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c30: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5c40: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5c50: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c70: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5c80: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5c90: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cb0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5cc0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5cd0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cf0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5d00: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5d10: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d20: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d40: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
5d50: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
5d60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d90: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5da0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5db0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5dd0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5de0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5df0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e10: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5e20: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5e30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e50: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5e60: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5e70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5ea0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5eb0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ed0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5ee0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5ef0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f10: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5f20: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5f30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f50: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5f60: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5f70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fa0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
5fb0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
5fc0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5fd0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ff0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6000: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6010: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6020: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6040: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6050: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6060: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6070: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6080: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6090: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
60a0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
60b0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
60c0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
60d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
60e0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
60f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6100: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6110: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6120: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6130: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6140: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6150: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6160: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6170: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6180: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6190: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
61a0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
61b0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
61c0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
61d0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
61e0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
61f0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6200: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6210: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6220: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6240: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6250: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6260: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6270: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6280: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6290: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
62a0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
62b0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
62c0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
62d0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
62e0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
62f0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6300: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6310: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6320: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6330: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6340: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6350: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6360: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6370: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6380: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6390: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
63a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
63b0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
63c0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
63d0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
63e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63f0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6400: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6410: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6420: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6430: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6440: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6450: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6460: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6470: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6480: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6490: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
64a0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
64b0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
64c0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
64d0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
64e0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
64f0: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6500: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6510: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6520: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6530: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6540: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6550: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6560: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6570: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6580: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6590: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
65a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
65b0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
65c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
65d0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
65e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
65f0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6600: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6620: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6630: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6640: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6650: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6670: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6680: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6690: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
66a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
66b0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
66c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
66d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
66e0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
66f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6700: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6710: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6720: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6730: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6750: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6760: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6770: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6780: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6790: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
67a0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
67b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
67c0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
67d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
67e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
67f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6800: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6810: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6830: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6840: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6850: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6860: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6870: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6880: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6890: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
68a0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
68b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
68c0: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
68d0: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
68e0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
68f0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6900: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6910: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6930: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6950: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6960: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6970: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6980: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6990: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
69a0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
69b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
69c0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
69d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
69e0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
69f0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6a00: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6a10: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6a20: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6a30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6a40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6a50: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6a60: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6a70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6a80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6a90: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6aa0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6ab0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6ac0: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6ad0: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6ae0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6af0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6b00: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6b10: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6b20: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6b30: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6b40: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6b50: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6b60: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6b70: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6b80: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6b90: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6ba0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6bb0: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6bc0: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6bd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6be0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6bf0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6c00: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6c10: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6c20: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6c30: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6c40: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6c50: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6c60: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6c70: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6c80: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6c90: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6ca0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
6cb0: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
6cc0: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
6cd0: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
6ce0: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
6cf0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
6d00: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
6d10: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
6d20: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
6d30: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
6d40: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6d50: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
6d60: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
6d70: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
6d80: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
6d90: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
6da0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
6db0: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
6dc0: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
6dd0: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
6de0: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
6df0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
6e00: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
6e10: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6e20: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
6e30: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
6e40: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
6e50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6e70: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
6e80: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
6e90: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
6ea0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
6eb0: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
6ec0: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
6ed0: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
6ee0: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
6ef0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6f00: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6f10: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6f20: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
6f30: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
6f40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6f50: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
6f60: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
6f70: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6f80: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
6f90: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
6fa0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6fb0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6fc0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
6fd0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
6fe0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
6ff0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7000: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7010: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7020: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7030: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7040: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7050: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7060: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7070: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7080: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7090: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
70a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
70b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
70c0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
70d0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
70e0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
70f0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7100: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7110: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7120: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7130: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7140: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7150: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7160: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7170: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7180: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7190: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
71a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
71b0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
71c0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
71d0: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
71e0: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
71f0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7200: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7210: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7220: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7240: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7250: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7260: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7270: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7280: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7290: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
72a0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
72b0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
72c0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
72d0: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
72e0: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
72f0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7300: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7310: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7320: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7330: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7340: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7350: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7360: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7370: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7380: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7390: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
73a0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
73b0: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
73c0: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
73d0: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
73e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
73f0: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7400: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7410: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7420: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7430: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7440: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7450: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7460: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7480: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7490: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
74a0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
74b0: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
74c0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
74d0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
74e0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
74f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7500: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7510: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7520: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7530: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7540: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7550: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7560: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7570: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7580: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7590: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
75a0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
75b0: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
75c0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
75d0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
75e0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
75f0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7600: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7610: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7620: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7630: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7640: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7650: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7660: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7670: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7680: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7690: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
76a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
76b0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
76c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
76d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
76e0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
76f0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7700: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7710: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7720: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7730: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7740: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7750: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7770: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7780: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7790: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
77a0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
77b0: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
77c0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
77d0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
77e0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
77f0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7800: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7810: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7820: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7830: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7840: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7850: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7860: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7870: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7880: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7890: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
78a0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
78b0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
78c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
78d0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
78e0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
78f0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7900: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7910: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7920: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7930: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7940: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7950: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7960: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7970: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7980: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7990: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
79a0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
79b0: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
79c0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
79d0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
79e0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
79f0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7a00: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7a10: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7a20: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7a30: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7a40: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7a50: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7a60: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7a70: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7a80: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7a90: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7aa0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7ab0: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7ac0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7ad0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7ae0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7af0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7b00: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7b10: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7b20: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7b30: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7b40: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7b50: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7b60: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7b70: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7b80: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7b90: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7ba0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7bb0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7bc0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7bd0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7be0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7bf0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7c00: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7c10: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7c20: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7c30: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7c40: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7c50: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7c60: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7c70: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7c80: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7c90: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7ca0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7cb0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7cc0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7cd0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7ce0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7cf0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7d00: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7d10: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7d20: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
7d30: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
7d40: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
7d50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7d60: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
7d70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7d80: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7d90: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7db0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7dc0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7dd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7de0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7df0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e00: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7e10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e20: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
7e30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7e40: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
7e50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
7e70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7e80: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7e90: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7ea0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7eb0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7ec0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7ed0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7ee0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7ef0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7f00: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7f10: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7f20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
7f30: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
7f40: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
7f50: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
7f60: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
7f70: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
7f80: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7f90: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7fa0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7fb0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7fc0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7fd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7fe0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7ff0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8000: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8010: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8020: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8030: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8040: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8050: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8060: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8070: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8080: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8090: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
80a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
80b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
80c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
80d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
80e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
80f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8100: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8110: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8120: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8130: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8140: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8150: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8160: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8170: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8180: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8190: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
81a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
81b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
81c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
81d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
81e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
81f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8200: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8210: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8220: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8230: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8240: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8250: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8260: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8270: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8280: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8290: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
82a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
82b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
82c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
82d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
82e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
82f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8300: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8310: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8320: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8330: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8340: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8350: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8360: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8370: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8380: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8390: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
83a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
83b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
83c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
83d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
83e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
83f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8400: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8410: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8420: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8430: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8440: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8450: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8460: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8470: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8480: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8490: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
84a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
84b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
84c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
84d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
84e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
84f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8500: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8510: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8520: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8530: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8540: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8550: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8560: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8570: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8580: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8590: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
85a0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
85b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
85c0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
85d0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
85e0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
85f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8600: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8610: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8620: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8640: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8650: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8660: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8690: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
86a0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
86b0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
86c0: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
86d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
86e0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
86f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8700: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8710: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8720: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8730: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
8740: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8750: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8760: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8770: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8780: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8790: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
87a0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
87b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
87c0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
87d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
87e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
87f0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8800: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8810: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8820: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8830: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8840: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8850: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8860: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8870: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8880: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8890: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
88a0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
88b0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
88c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
88d0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
88e0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
88f0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8900: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8910: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8920: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8930: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8940: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8950: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8960: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8970: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8980: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8990: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
89a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
89b0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
89c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
89d0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
89e0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
89f0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8a00: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8a10: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8a20: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8a30: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8a40: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8a50: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8a60: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8a70: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8a80: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8a90: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8aa0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8ab0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8ac0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8ad0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8ae0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8af0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8b00: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8b10: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8b20: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8b30: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8b40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8b50: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8b60: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8b70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8b80: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8b90: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8ba0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8bb0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8bc0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8bd0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8be0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8bf0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8c00: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8c10: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c30: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8c40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8c50: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8c60: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8c70: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8c80: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8c90: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8ca0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
8cb0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
8cc0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
8cd0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
8ce0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
8cf0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8d00: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8d10: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8d20: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8d30: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
8d40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8d50: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
8d60: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
8d70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8d80: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
8d90: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
8da0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
8db0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
8dc0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
8dd0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
8de0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
8df0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
8e00: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
8e10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8e20: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
8e30: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
8e40: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
8e50: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8e60: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8e70: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
8e80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8e90: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8ea0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8eb0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8ec0: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
8ed0: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
8ee0: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
8ef0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8f00: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8f10: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
8f20: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
8f30: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
8f40: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
8f50: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
8f60: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
8f70: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8f80: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8f90: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8fa0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8fb0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8fc0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
8fd0: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
8fe0: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
8ff0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
9000: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
9010: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9020: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
9030: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9040: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9050: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9060: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
9070: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9080: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9090: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
90a0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
90b0: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
90c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
90d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
90e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
90f0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9100: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9110: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9120: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9130: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9140: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9150: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9160: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9170: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9180: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9190: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
91a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
91b0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
91c0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
91d0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
91e0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
91f0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9200: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9210: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9220: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9230: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9240: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9250: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9260: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9270: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9280: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9290: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
92a0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
92b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
92c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
92d0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
92e0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
92f0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9300: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9310: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9320: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9330: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9340: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9350: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9360: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9370: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9380: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9390: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
93a0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
93b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
93c0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
93d0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
93e0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
93f0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9400: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9410: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9420: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9430: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9440: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9450: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9460: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9470: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9480: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9490: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
94a0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
94b0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
94c0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
94d0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
94e0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
94f0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9500: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9510: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9520: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9530: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9540: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9550: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9560: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9570: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9580: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9590: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
95a0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
95b0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
95c0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
95d0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
95e0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
95f0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9600: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9610: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9620: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9630: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9640: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9650: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9660: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9670: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9680: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9690: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
96a0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
96b0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
96c0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
96d0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
96e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
96f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9700: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9710: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9720: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9730: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9740: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9750: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9760: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9770: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9780: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9790: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
97a0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
97b0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
97c0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
97e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
97f0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9800: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9820: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9830: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9840: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9850: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9860: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9870: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9880: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9890: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
98a0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
98b0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
98c0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
98d0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
98e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
98f0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9900: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9910: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9920: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9930: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9940: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9950: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9960: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9970: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9980: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9990: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
99a0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
99b0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
99c0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
99d0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
99e0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
99f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9a00: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9a10: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9a20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9a30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9a40: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9a50: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9a60: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9a70: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9a80: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9a90: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9aa0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9ab0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
9ac0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9ad0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9ae0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9af0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9b00: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9b10: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9b20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b30: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9b40: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9b50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9b60: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9b70: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9b80: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9b90: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
9ba0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
9bb0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
9bc0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
9bd0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
9be0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
9bf0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9c00: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9c10: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9c20: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9c30: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9c40: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
9c50: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
9c60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9c70: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
9c80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9c90: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
9ca0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
9cb0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
9cc0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
9cd0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
9ce0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
9cf0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
9d00: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
9d10: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
9d20: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
9d30: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
9d40: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
9d50: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
9d60: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
9d70: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
9d80: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
9d90: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
9da0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
9db0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
9dc0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
9dd0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
9de0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
9df0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
9e00: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
9e10: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
9e20: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
9e30: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
9e40: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
9e50: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
9e60: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
9e70: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
9e80: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
9e90: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
9ea0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
9eb0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
9ec0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
9ed0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
9ee0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
9ef0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
9f00: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
9f10: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
9f20: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
9f30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9f40: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
9f50: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
9f60: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
9f70: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
9f80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
9f90: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9fa0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
9fb0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
9fc0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
9fd0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
9fe0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
9ff0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a000: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a010: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a020: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a030: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a040: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a050: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a060: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a070: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a080: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a090: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a0a0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a0b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a0c0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a0d0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a0e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a0f0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a100: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a110: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a120: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a130: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a140: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a150: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a160: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a170: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a180: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a190: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a1a0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a1b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a1c0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a1d0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a1e0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a1f0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a200: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a210: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a220: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a230: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a240: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a250: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a260: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a270: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a280: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a290: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a2a0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a2b0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a2c0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a2d0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a2e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a2f0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a300: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a310: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a320: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a330: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a340: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a350: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a360: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a370: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a380: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a390: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a3a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a3b0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a3c0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a3d0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a3e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a3f0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a400: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a410: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
a420: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
a430: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
a440: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
a450: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
a460: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
a470: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
a480: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a490: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a4a0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
a4b0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
a4c0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
a4d0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
a4e0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
a4f0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
a500: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
a510: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
a520: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a530: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a540: 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65  ]].** ^This file
a550: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
a560: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a570: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
a580: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
a590: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
a5a0: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
a5b0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a5c0: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
a5d0: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
a5e0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
a5f0: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
a600: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
a610: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
a620: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
a630: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
a640: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
a650: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
a660: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
a670: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
a680: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
a690: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
a6a0: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
a6b0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
a6c0: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
a6d0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
a6e0: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
a6f0: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
a700: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
a710: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
a720: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
a730: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
a740: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
a750: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
a760: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
a770: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
a780: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
a790: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
a7a0: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
a7b0: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
a7c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a7d0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
a7e0: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
a7f0: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
a800: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a810: 6c 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  l to have SQLite
a820: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
a830: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
a840: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
a850: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
a860: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
a870: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
a880: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
a890: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
a8a0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
a8b0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
a8c0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
a8d0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
a8e0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
a8f0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
a900: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
a910: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a920: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a930: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
a940: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
a950: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
a960: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
a970: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
a980: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
a990: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a9a0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 4c 49  TE_FCNTL_MMAP_LI
a9b0: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 61 72 67  MIT]].** The arg
a9c0: 75 6d 65 6e 74 20 69 73 20 61 73 73 75 6d 65 64  ument is assumed
a9d0: 20 74 6f 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   to pointer to a
a9e0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
a9f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
aa00: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
aa10: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
aa20: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
aa30: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
aa40: 79 20 6d 61 70 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  y map..**.** </u
aa50: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
aa60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
aa70: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
aa80: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
aa90: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
aaa0: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
aab0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
aac0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
aad0: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
aae0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
aaf0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
ab00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ab10: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
ab20: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
ab30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
ab40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ab50: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
ab60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
ab70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ab80: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
ab90: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
aba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
abb0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
abc0: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
abd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
abe0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
abf0: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
ac00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ac10: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
ac20: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
ac30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ac40: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
ac50: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
ac60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ac70: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
ac80: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
ac90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
aca0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
acb0: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
acc0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
acd0: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
ace0: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
acf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
ad00: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
ad10: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
ad20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
ad30: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
ad40: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
ad50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
ad60: 4c 49 4d 49 54 20 20 20 20 20 20 20 20 20 20 20  LIMIT           
ad70: 20 20 31 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    18../*.** CAPI
ad80: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
ad90: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
ada0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
adb0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
adc0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
add0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
ade0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
adf0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
ae00: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
ae10: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
ae20: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
ae30: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
ae40: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
ae50: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
ae60: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
ae70: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
ae80: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
ae90: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
aea0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
aeb0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
aec0: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
aed0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
aee0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
aef0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
af00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
af10: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
af20: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
af30: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
af40: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
af50: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
af60: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
af70: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
af80: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
af90: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
afa0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
afb0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
afc0: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
afd0: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
afe0: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
aff0: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
b000: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
b010: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
b020: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
b030: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
b040: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
b050: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
b060: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
b070: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
b080: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
b090: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
b0a0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
b0b0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
b0c0: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
b0d0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
b0e0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
b0f0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
b100: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
b110: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
b120: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
b130: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
b140: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
b150: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
b160: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
b170: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
b180: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
b190: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
b1a0: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
b1b0: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
b1c0: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
b1d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
b1e0: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
b1f0: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
b200: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
b210: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
b220: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
b230: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
b240: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
b250: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
b260: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
b270: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
b280: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
b290: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
b2a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
b2b0: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
b2c0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
b2d0: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
b2e0: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
b2f0: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
b300: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
b310: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
b320: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
b330: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
b340: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
b350: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
b360: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
b370: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
b380: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
b390: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
b3a0: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
b3b0: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
b3c0: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
b3d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
b3e0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
b3f0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
b400: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
b410: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
b420: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
b430: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
b440: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
b450: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
b460: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
b470: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
b480: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
b490: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
b4a0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
b4b0: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
b4c0: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
b4d0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
b4e0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
b4f0: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
b500: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
b510: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
b520: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
b530: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
b540: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
b550: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
b560: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
b570: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
b580: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
b590: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
b5a0: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
b5b0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
b5c0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
b5d0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
b5e0: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
b5f0: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
b600: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
b610: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
b620: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
b630: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
b640: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
b650: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
b660: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
b670: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
b680: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
b690: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
b6a0: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
b6b0: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
b6c0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
b6d0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
b6e0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
b6f0: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
b700: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
b710: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
b720: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
b730: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
b740: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
b750: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
b760: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
b770: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
b780: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
b790: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
b7a0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
b7b0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
b7c0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
b7d0: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
b7e0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
b7f0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
b800: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
b810: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
b820: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
b830: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
b840: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
b850: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
b860: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
b870: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
b880: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
b890: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
b8a0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
b8b0: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
b8c0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
b8d0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
b8e0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
b8f0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
b900: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
b910: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
b920: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
b930: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
b940: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
b950: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
b960: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
b970: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
b980: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
b990: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
b9a0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
b9b0: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
b9c0: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
b9d0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
b9e0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
b9f0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
ba00: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
ba10: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
ba20: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
ba30: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
ba40: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
ba50: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
ba60: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
ba70: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
ba80: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
ba90: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
baa0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
bab0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
bac0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
bad0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
bae0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
baf0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
bb00: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
bb10: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
bb20: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
bb30: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
bb40: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
bb50: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
bb60: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
bb70: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
bb80: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
bb90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
bba0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
bbb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
bbc0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
bbd0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
bbe0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
bbf0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
bc00: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
bc10: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
bc20: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
bc30: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
bc40: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
bc50: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
bc60: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
bc70: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
bc80: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
bc90: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
bca0: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
bcb0: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
bcc0: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
bcd0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
bce0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
bcf0: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
bd00: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
bd10: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
bd20: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
bd30: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
bd40: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
bd50: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
bd60: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
bd70: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
bd80: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
bd90: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
bda0: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
bdb0: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
bdc0: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
bdd0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
bde0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
bdf0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
be00: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
be10: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
be20: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
be30: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
be40: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
be50: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
be60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
be70: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
be80: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
be90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
bea0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
beb0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
bec0: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
bed0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
bee0: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
bef0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
bf00: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
bf10: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
bf20: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
bf30: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
bf40: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
bf50: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
bf60: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
bf70: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
bf80: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
bf90: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
bfa0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
bfb0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
bfc0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
bfd0: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
bfe0: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
bff0: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
c000: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
c010: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
c020: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
c030: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
c040: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
c050: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
c060: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
c070: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
c080: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
c090: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
c0a0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
c0b0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
c0c0: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
c0d0: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
c0e0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
c0f0: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
c100: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
c110: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
c120: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
c130: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
c140: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
c150: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
c160: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
c170: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
c180: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
c190: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
c1a0: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
c1b0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
c1c0: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
c1d0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
c1e0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
c1f0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
c200: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
c210: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
c220: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
c230: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
c240: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
c250: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
c260: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
c270: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
c280: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
c290: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
c2a0: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
c2b0: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
c2c0: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
c2d0: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
c2e0: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
c2f0: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
c300: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
c310: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
c320: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
c330: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
c340: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
c350: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
c360: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
c370: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
c380: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
c390: 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
c3a0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
c3b0: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
c3c0: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
c3d0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
c3e0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
c3f0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
c400: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
c410: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
c420: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
c430: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
c440: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
c450: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
c460: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
c470: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
c480: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
c490: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
c4a0: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
c4b0: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
c4c0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
c4d0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
c4e0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
c4f0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
c500: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
c510: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
c520: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
c530: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
c540: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
c550: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
c560: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
c570: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
c580: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
c590: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
c5a0: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
c5b0: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
c5c0: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
c5d0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
c5e0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
c5f0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
c600: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
c610: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
c620: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
c630: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
c640: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
c650: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
c660: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
c670: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
c680: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
c690: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
c6a0: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
c6b0: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
c6c0: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
c6d0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
c6e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
c6f0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
c700: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
c710: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
c720: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
c730: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
c740: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
c750: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
c760: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
c770: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
c780: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
c790: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
c7a0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
c7b0: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
c7c0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
c7d0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
c7e0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
c7f0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
c800: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
c810: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
c820: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
c830: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
c840: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
c850: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
c860: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
c870: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
c880: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
c890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
c8a0: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
c8b0: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
c8c0: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
c8d0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
c8e0: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
c8f0: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
c900: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
c910: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
c920: 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
c930: 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
c940: 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
c950: 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
c960: 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
c970: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
c980: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
c990: 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
c9a0: 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
c9b0: 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
c9c0: 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
c9d0: 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
c9e0: 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
c9f0: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
ca00: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
ca10: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
ca20: 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
ca30: 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
ca40: 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
ca50: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
ca60: 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
ca70: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
ca80: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
ca90: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
caa0: 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
cab0: 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
cac0: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
cad0: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
cae0: 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
caf0: 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
cb00: 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
cb10: 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
cb20: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
cb30: 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
cb40: 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
cb50: 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
cb60: 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
cb70: 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
cb80: 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
cb90: 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
cba0: 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
cbb0: 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
cbc0: 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
cbd0: 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
cbe0: 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
cbf0: 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
cc00: 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
cc10: 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
cc20: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
cc30: 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
cc40: 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
cc50: 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
cc60: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
cc70: 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
cc80: 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
cc90: 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
cca0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
ccb0: 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
ccc0: 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
ccd0: 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
cce0: 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
ccf0: 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
cd00: 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
cd10: 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
cd20: 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
cd30: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
cd40: 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
cd50: 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
cd60: 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
cd70: 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
cd80: 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
cd90: 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
cda0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
cdb0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
cdc0: 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
cdd0: 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
cde0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
cdf0: 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
ce00: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
ce10: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
ce20: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
ce30: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
ce40: 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
ce50: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
ce60: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
ce70: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
ce80: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
ce90: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
cea0: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
ceb0: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
cec0: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
ced0: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
cee0: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
cef0: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
cf00: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
cf10: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
cf20: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
cf30: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
cf40: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
cf50: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
cf60: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
cf70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
cf80: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
cf90: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
cfa0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
cfb0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
cfc0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
cfd0: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
cfe0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
cff0: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
d000: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
d010: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d020: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
d030: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
d040: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
d050: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d060: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
d070: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
d080: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
d090: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
d0a0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
d0b0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
d0c0: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
d0d0: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
d0e0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
d0f0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d100: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
d110: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
d120: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d130: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
d140: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
d150: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
d160: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
d170: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
d180: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
d190: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
d1a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
d1b0: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
d1c0: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
d1d0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
d1e0: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
d1f0: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
d200: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
d210: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
d220: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
d230: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
d240: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
d250: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
d260: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
d270: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
d280: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
d290: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
d2a0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
d2b0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
d2c0: 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
d2d0: 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
d2e0: 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
d2f0: 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
d300: 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
d310: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
d320: 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
d330: 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
d340: 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
d350: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
d360: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
d370: 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
d380: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
d390: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
d3a0: 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
d3b0: 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
d3c0: 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
d3d0: 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
d3e0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
d3f0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d400: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
d410: 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
d420: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
d430: 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
d440: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d450: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d460: 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
d470: 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
d480: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
d490: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d4a0: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
d4b0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
d4c0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
d4d0: 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
d4e0: 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
d4f0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
d500: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
d510: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
d520: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
d530: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
d540: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
d550: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
d560: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
d570: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
d580: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
d590: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
d5a0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
d5b0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
d5c0: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
d5d0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
d5e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
d5f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
d600: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
d610: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
d620: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
d630: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
d640: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
d650: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
d660: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
d670: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
d680: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
d690: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
d6a0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
d6b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
d6c0: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
d6d0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
d6e0: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
d6f0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
d700: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
d710: 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
d720: 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
d730: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
d740: 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
d750: 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
d760: 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
d770: 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
d780: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
d790: 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
d7a0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
d7b0: 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
d7c0: 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
d7d0: 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
d7e0: 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
d7f0: 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
d800: 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
d810: 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
d820: 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
d830: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
d840: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
d850: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
d860: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
d870: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
d880: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
d890: 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
d8a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
d8b0: 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
d8c0: 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
d8d0: 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
d8e0: 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
d8f0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
d900: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
d910: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
d920: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
d930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d940: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
d950: 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
d960: 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
d970: 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
d980: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
d990: 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
d9a0: 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
d9b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
d9c0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
d9d0: 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
d9e0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
d9f0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
da00: 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
da10: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
da20: 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
da30: 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
da40: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
da50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
da60: 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
da70: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
da80: 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
da90: 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
daa0: 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
dab0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
dac0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
dad0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
dae0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
daf0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
db00: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
db10: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
db20: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
db30: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
db40: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
db50: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
db60: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
db70: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
db80: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
db90: 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
dba0: 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
dbb0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
dbc0: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
dbd0: 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
dbe0: 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  no the correspon
dbf0: 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
dc00: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
dc10: 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
dc20: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
dc30: 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
dc40: 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
dc50: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
dc60: 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
dc70: 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
dc80: 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
dc90: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
dca0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dcb0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
dcc0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
dcd0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
dce0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
dcf0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
dd00: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
dd10: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
dd20: 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
dd30: 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
dd40: 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
dd50: 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
dd60: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
dd70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
dd80: 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
dd90: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
dda0: 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
ddb0: 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
ddc0: 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
ddd0: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
dde0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
ddf0: 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
de00: 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
de10: 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
de20: 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
de30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
de40: 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
de50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
de60: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
de70: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
de80: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
de90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dea0: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
deb0: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
dec0: 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
ded0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
dee0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
def0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
df00: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
df10: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
df20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
df30: 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
df40: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
df50: 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
df60: 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
df70: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
df80: 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
df90: 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
dfa0: 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
dfb0: 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
dfc0: 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
dfd0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
dfe0: 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
dff0: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
e000: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
e010: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e020: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
e030: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
e040: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
e050: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
e060: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
e070: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
e080: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
e090: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
e0a0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
e0b0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
e0c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
e0d0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
e0e0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
e0f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e100: 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
e110: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
e120: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
e130: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
e140: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
e150: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
e160: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
e170: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
e180: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
e190: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
e1a0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
e1b0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
e1c0: 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
e1d0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e1e0: 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
e1f0: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
e200: 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
e210: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
e220: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
e230: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
e240: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
e250: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
e260: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
e270: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
e280: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
e290: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
e2a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e2b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
e2c0: 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
e2d0: 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
e2e0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
e2f0: 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
e300: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e310: 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
e320: 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
e330: 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
e340: 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
e350: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
e360: 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
e370: 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
e380: 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
e390: 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
e3a0: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
e3b0: 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
e3c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
e3d0: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
e3e0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
e3f0: 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
e400: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
e410: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
e420: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
e430: 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
e440: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
e450: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
e460: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
e470: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
e480: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
e490: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
e4a0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
e4b0: 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
e4c0: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
e4d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
e4e0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
e4f0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
e500: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
e510: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
e520: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
e530: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
e540: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
e550: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
e560: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
e570: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
e580: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
e590: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e5a0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
e5b0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
e5c0: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
e5d0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
e5e0: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
e5f0: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
e600: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
e610: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
e620: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e630: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
e640: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
e650: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
e660: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
e670: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
e680: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
e690: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
e6a0: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
e6b0: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
e6c0: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
e6d0: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
e6e0: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
e6f0: 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
e700: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
e710: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
e720: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
e730: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
e740: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e750: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
e760: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
e770: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e780: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
e790: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
e7a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
e7b0: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
e7c0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
e7d0: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
e7e0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
e7f0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
e800: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
e810: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
e820: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
e830: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
e840: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
e850: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e860: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
e870: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
e880: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
e890: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
e8a0: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
e8b0: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
e8c0: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
e8d0: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
e8e0: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
e8f0: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
e900: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
e910: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
e920: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
e930: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
e940: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
e950: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
e960: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
e970: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e980: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
e990: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
e9a0: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
e9b0: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
e9c0: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
e9d0: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
e9e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
e9f0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
ea00: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
ea10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ea20: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
ea30: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
ea40: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
ea50: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
ea60: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
ea70: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
ea80: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
ea90: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
eaa0: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
eab0: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
eac0: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
ead0: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
eae0: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
eaf0: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
eb00: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
eb10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
eb20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
eb30: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
eb40: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
eb50: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
eb60: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
eb70: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
eb80: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
eb90: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
eba0: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
ebb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ebc0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
ebd0: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
ebe0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ebf0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
ec00: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
ec10: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
ec20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
ec30: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
ec40: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
ec50: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
ec60: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
ec70: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
ec80: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
ec90: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
eca0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ecb0: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
ecc0: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
ecd0: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
ece0: 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
ecf0: 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
ed00: 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
ed10: 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
ed20: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
ed30: 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
ed40: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
ed50: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
ed60: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
ed70: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
ed80: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
ed90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
eda0: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
edb0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
edc0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
edd0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
ede0: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
edf0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
ee00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
ee10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ee20: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
ee30: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
ee40: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
ee50: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
ee60: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
ee70: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
ee80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
ee90: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
eea0: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
eeb0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
eec0: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
eed0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
eee0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
eef0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
ef00: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
ef10: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
ef20: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ef30: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
ef40: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
ef50: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
ef60: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
ef70: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
ef80: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
ef90: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
efa0: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
efb0: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
efc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
efd0: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
efe0: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
eff0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
f000: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
f010: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
f020: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
f030: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
f040: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
f050: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
f060: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
f070: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f080: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
f090: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
f0a0: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
f0b0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
f0c0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
f0d0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
f0e0: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
f0f0: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
f100: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
f110: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f120: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
f130: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
f140: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
f150: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
f160: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
f170: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
f180: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
f190: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
f1a0: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
f1b0: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
f1c0: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
f1d0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
f1e0: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
f1f0: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
f200: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
f210: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
f220: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
f230: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
f240: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
f250: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
f260: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
f270: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
f280: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
f290: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
f2a0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
f2b0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
f2c0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
f2d0: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
f2e0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f2f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
f300: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
f310: 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
f320: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
f330: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
f340: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
f350: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
f360: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
f370: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
f380: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
f390: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
f3a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f3b0: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
f3c0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
f3d0: 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
f3e0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
f3f0: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
f400: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
f410: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
f420: 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
f430: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
f440: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
f450: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
f460: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
f470: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
f480: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
f490: 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
f4a0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
f4b0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
f4c0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f4d0: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
f4e0: 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
f4f0: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
f500: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
f510: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
f520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
f530: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
f540: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f550: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
f560: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
f570: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
f580: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
f590: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
f5a0: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
f5b0: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
f5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
f5d0: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
f5e0: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
f5f0: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
f600: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
f610: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
f620: 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
f630: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
f640: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
f650: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
f660: 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
f670: 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
f680: 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
f690: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
f6a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f6b0: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
f6c0: 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
f6d0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
f6e0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
f6f0: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
f700: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
f710: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
f720: 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
f730: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
f740: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
f750: 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
f760: 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
f770: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
f780: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
f790: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
f7a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f7b0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
f7c0: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
f7d0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
f7e0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
f7f0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
f800: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
f810: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
f820: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
f830: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
f840: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
f850: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
f860: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
f870: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
f880: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
f890: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
f8a0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
f8b0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
f8c0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f8d0: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
f8e0: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
f8f0: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
f900: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f910: 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
f920: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
f930: 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
f940: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
f950: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
f960: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
f970: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
f980: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
f990: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
f9a0: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
f9b0: 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
f9c0: 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
f9d0: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
f9e0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
f9f0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
fa00: 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
fa10: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
fa20: 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
fa30: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
fa40: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
fa50: 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
fa60: 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
fa70: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
fa80: 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
fa90: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
faa0: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
fab0: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
fac0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
fad0: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
fae0: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
faf0: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
fb00: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
fb10: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
fb20: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
fb30: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
fb40: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
fb50: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
fb60: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
fb70: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
fb80: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
fb90: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
fba0: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
fbb0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
fbc0: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
fbd0: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
fbe0: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
fbf0: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
fc00: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
fc10: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
fc20: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
fc30: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
fc40: 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
fc50: 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
fc60: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
fc70: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
fc80: 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
fc90: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
fca0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
fcb0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
fcc0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
fcd0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
fce0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
fcf0: 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
fd00: 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
fd10: 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
fd20: 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
fd30: 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
fd40: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
fd50: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
fd60: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
fd70: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
fd80: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
fd90: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
fda0: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
fdb0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
fdc0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
fdd0: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
fde0: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
fdf0: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
fe00: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
fe10: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
fe20: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
fe30: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
fe40: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
fe50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fe60: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
fe70: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
fe80: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
fe90: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
fea0: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
feb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
fec0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
fed0: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
fee0: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
fef0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
ff00: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
ff10: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
ff20: 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
ff30: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ff40: 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
ff50: 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
ff60: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
ff70: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
ff80: 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
ff90: 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
ffa0: 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
ffb0: 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
ffc0: 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
ffd0: 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
ffe0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
fff0: 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
10000 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
10010 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
10020 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
10030 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
10040 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
10050 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
10060 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
10070 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
10080 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
10090 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
100a0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
100b0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
100c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
100d0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
100e0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
100f0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
10100 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
10110 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
10120 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
10130 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
10140 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
10150 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
10160 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
10170 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
10180 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
10190 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
101a0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
101b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
101c0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
101d0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
101e0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
101f0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
10200 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
10210 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
10220 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
10230 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
10240 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
10250 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
10260 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
10270 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
10280 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
10290 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
102a0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
102b0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
102c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
102d0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
102e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
102f0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
10300 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
10310 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
10320 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
10330 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
10340 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
10350 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
10360 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
10370 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
10380 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
10390 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
103a0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
103b0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
103c0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
103d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
103e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
103f0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
10400 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
10410 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
10420 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
10430 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
10440 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
10450 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
10460 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
10470 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10480 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
10490 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
104a0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
104b0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
104c0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
104d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
104e0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
104f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
10500 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
10510 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
10520 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
10530 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
10540 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
10550 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
10560 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
10570 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
10580 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
10590 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
105a0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
105b0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
105c0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
105d0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
105e0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
105f0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
10600 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
10610 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
10620 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
10630 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
10640 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
10650 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
10660 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
10670 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10680 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
10690 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
106a0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
106b0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
106c0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
106d0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
106e0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
106f0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
10700 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
10710 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
10720 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
10730 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
10740 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
10750 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10760 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
10770 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
10780 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10790 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
107a0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
107b0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
107c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
107d0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
107e0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
107f0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
10800 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
10810 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10820 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
10830 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
10840 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
10850 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
10860 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
10870 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
10880 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
10890 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
108a0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
108b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
108c0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
108d0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
108e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
108f0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
10900 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
10910 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10920 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
10930 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
10940 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10950 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
10960 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10970 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
10980 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
10990 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
109a0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
109b0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
109c0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
109d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
109e0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
109f0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
10a00 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
10a10 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
10a20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
10a30 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
10a40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
10a50 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
10a60 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
10a70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10a80 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
10a90 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10aa0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
10ab0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
10ac0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
10ad0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
10ae0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
10af0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
10b00 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
10b10 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
10b20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
10b30 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
10b40 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
10b50 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
10b60 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
10b70 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
10b80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
10b90 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
10ba0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10bb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10bd0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
10be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10bf0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
10c00 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
10c10 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
10c20 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
10c30 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
10c40 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
10c50 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
10c60 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
10c70 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
10c80 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
10c90 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
10ca0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
10cb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10cc0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
10cd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
10ce0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
10cf0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
10d00 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
10d10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
10d20 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
10d30 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
10d40 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
10d50 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
10d60 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
10d70 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
10d80 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
10d90 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
10da0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
10db0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
10dc0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
10dd0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
10de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
10df0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
10e00 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
10e10 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10e20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10e30 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
10e40 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
10e50 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
10e60 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
10e70 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
10e80 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
10e90 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
10ea0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
10eb0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10ec0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
10ed0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10ee0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
10ef0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
10f00 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
10f10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10f20 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
10f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
10f40 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
10f50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
10f60 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
10f70 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
10f80 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
10f90 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
10fa0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
10fb0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
10fc0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
10fd0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
10fe0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
10ff0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
11000 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
11010 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
11020 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
11030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11040 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11050 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11060 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
11070 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
11080 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
11090 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
110a0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
110b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
110c0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
110d0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
110e0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
110f0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
11100 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
11110 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11120 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
11130 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
11140 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
11150 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
11160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11170 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
11180 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11190 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
111a0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
111b0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
111c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
111d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
111e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
111f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11200 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11210 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11220 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11230 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
11240 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
11250 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11260 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11270 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11280 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
11290 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
112a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
112b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
112c0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
112d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
112e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
112f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
11300 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11310 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
11320 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
11330 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
11340 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
11350 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
11360 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
11370 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
11380 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
11390 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
113a0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
113b0 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
113c0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
113d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
113e0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
113f0 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
11400 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11410 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
11420 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11430 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
11440 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
11450 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
11460 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
11470 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11480 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
11490 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
114a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
114b0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
114c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
114d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
114e0 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
114f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
11500 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
11510 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
11520 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11530 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11540 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11550 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11560 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
11570 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11580 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
11590 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
115a0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
115b0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
115c0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
115d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
115e0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
115f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
11600 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
11610 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
11620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11630 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
11640 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
11650 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
11660 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11670 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
11680 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
11690 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
116a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
116b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
116c0 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
116d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
116e0 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
116f0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
11700 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
11710 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
11720 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
11730 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77  a .** boolean, w
11740 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
11750 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
11760 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
11770 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a  y allocation .**
11780 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
11790 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
117a0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
117b0 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74   are disabled, t
117c0 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  he .** following
117d0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
117e0 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
117f0 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
11800 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
11810 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
11820 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
11830 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
11840 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
11850 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11860 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
11870 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
11880 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
11890 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
118a0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
118b0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
118c0 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
118d0 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
118e0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
118f0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
11900 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
11910 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
11920 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
11930 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
11940 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
11950 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
11960 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
11970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
11980 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
11990 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
119a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
119b0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
119c0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
119d0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
119e0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
119f0 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
11a00 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
11a10 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
11a20 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
11a30 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
11a40 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
11a50 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
11a60 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
11a70 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
11a80 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
11a90 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
11aa0 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
11ab0 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
11ac0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
11ad0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
11ae0 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
11af0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
11b00 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
11b10 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  16..** The first
11b20 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
11b30 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
11b40 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
11b50 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
11b60 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
11b70 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
11b80 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
11b90 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77   no more than tw
11ba0 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
11bb0 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53  s per thread.  S
11bc0 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
11bd0 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68   set to twice th
11be0 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
11bf0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
11c00 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  eads..** ^SQLite
11c10 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
11c20 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
11c30 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
11c40 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
11c50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
11c60 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
11c70 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
11c80 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
11c90 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
11ca0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
11cb0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
11cc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11cd0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
11ce0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
11cf0 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
11d00 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
11d10 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
11d20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11d30 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
11d40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11d50 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
11d60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
11d70 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
11d80 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
11d90 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
11da0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
11db0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
11dc0 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
11dd0 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
11de0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
11df0 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
11e00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
11e10 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
11e20 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
11e30 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
11e40 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
11e50 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
11e60 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
11e70 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
11e80 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  2 option..** The
11e90 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
11ea0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11eb0 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
11ec0 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
11ed0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
11ee0 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
11ef0 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
11f00 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
11f10 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
11f20 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
11f30 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
11f40 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
11f50 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
11f60 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
11f70 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
11f80 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
11f90 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
11fa0 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
11fb0 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
11fc0 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
11fd0 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
11fe0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
11ff0 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
12000 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
12010 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
12020 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
12030 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
12040 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
12050 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
12060 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
12070 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
12080 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
12090 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
120a0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
120b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
120c0 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
120d0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
120e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
120f0 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
12100 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
12110 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
12120 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
12130 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
12140 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
12150 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
12160 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
12170 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
12180 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
12190 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
121a0 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
121b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
121c0 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
121d0 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
121e0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   The pointer in 
121f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12200 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  nt must.** be al
12210 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
12220 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  te boundary or s
12230 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
12240 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
12250 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
12260 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
12270 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
12280 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
12290 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
122a0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
122b0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
122c0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
122d0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
122e0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
122f0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
12300 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
12310 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
12320 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
12330 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
12340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12350 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
12360 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12370 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
12380 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12390 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
123a0 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
123b0 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
123c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
123d0 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
123e0 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
123f0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
12400 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
12410 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
12420 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
12430 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
12440 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
12450 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
12460 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
12470 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
12480 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
12490 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
124a0 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
124b0 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
124c0 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
124d0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
124e0 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
124f0 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
12500 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
12510 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
12520 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
12530 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
12540 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
12550 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
12560 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
12570 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
12580 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
12590 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
125a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
125b0 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
125c0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
125d0 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
125e0 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
125f0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
12600 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
12610 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
12620 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
12630 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
12640 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
12650 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
12660 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
12670 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
12680 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
12690 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
126a0 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
126b0 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
126c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
126d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
126e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
126f0 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
12700 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12710 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12720 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12730 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12740 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12750 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12760 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12770 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
12780 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
12790 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
127a0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
127b0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
127c0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
127d0 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
127e0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
127f0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
12800 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
12810 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
12820 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12830 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
12840 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
12850 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
12860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12870 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
12880 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12890 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
128a0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
128b0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
128c0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
128d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
128e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
128f0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
12900 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
12910 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
12920 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
12930 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12940 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
12950 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12960 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
12970 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
12980 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
12990 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
129a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
129b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
129c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
129d0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
129e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
129f0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12a00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12a10 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12a20 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12a30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12a40 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12a50 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
12a60 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
12a70 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
12a80 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
12a90 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
12aa0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
12ab0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
12ac0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
12ad0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
12ae0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
12af0 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
12b00 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
12b10 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
12b20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
12b30 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
12b40 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
12b50 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
12b60 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
12b70 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12b80 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12b90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12ba0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12bb0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12bc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12bd0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
12be0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
12bf0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
12c00 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
12c10 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
12c20 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
12c30 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
12c40 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
12c50 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
12c60 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12c70 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
12c80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
12c90 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
12cb0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
12cc0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
12cd0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
12ce0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12cf0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
12d00 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
12d10 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
12d20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12d30 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
12d40 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
12d50 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
12d60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12d70 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
12d80 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
12d90 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
12da0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
12db0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
12dc0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
12dd0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
12de0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
12df0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
12e00 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
12e10 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12e20 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
12e30 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
12e40 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
12e50 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
12e60 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
12e70 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12e80 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
12e90 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
12ea0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
12eb0 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
12ec0 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
12ed0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
12ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12ef0 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
12f00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
12f10 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
12f20 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12f30 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12f40 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
12f50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
12f60 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
12f70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
12f80 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
12f90 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
12fa0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
12fb0 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
12fc0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12fd0 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
12fe0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
12ff0 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
13000 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
13010 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13020 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
13030 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13040 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13050 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13060 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13070 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
13080 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13090 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
130a0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
130b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
130c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
130d0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
130e0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
130f0 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
13100 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
13110 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13120 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
13130 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
13140 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13150 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
13160 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
13170 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
13180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13190 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
131a0 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
131b0 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
131c0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
131d0 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
131e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
131f0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
13200 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
13210 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
13220 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
13230 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
13240 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
13250 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
13260 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
13270 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
13280 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
13290 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
132a0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
132b0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
132c0 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
132d0 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
132e0 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
132f0 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
13300 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
13310 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
13320 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
13330 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
13340 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
13350 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
13360 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
13370 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
13380 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
13390 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
133a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
133b0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
133c0 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
133d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
133e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
133f0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
13400 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
13410 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
13420 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
13430 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
13440 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
13450 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
13460 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
13470 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
13480 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
13490 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
134a0 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
134b0 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
134c0 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
134d0 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
134e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
134f0 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
13500 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
13510 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
13520 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
13530 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
13540 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
13550 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
13560 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
13570 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
13580 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
13590 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
135a0 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
135b0 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
135c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
135d0 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
135e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
135f0 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
13600 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13610 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
13620 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
13630 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
13640 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
13650 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
13660 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
13670 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
13680 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
13690 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
136a0 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64  led. If URI hand
136b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
136c0 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
136d0 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
136e0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
136f0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
13700 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
13710 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
13720 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
13730 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
13740 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
13750 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
13760 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
13770 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
13780 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
13790 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
137a0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
137b0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
137c0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
137d0 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61  . If it is globa
137e0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
137f0 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
13800 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
13810 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
13820 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
13830 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
13840 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
13850 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
13860 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74  ened. By default
13870 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
13880 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
13890 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
138a0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
138b0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
138c0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
138d0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
138e0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
138f0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
13900 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
13910 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
13920 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13930 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
13940 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  SCAN.** <dd> Thi
13950 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13960 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20   single integer 
13970 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13980 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
13990 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  .** a boolean in
139a0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
139b0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
139c0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
139d0 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66  indices for.** f
139e0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
139f0 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
13a00 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64 65 66  imizer.  The def
13a10 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
13a20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
13a30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
13a40 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
13a50 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
13a60 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
13a70 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
13a80 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
13a90 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
13aa0 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
13ab0 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
13ac0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
13ad0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
13ae0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
13af0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
13b00 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
13b10 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
13b20 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
13b30 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66  function.** malf
13b40 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  unction when the
13b50 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
13b60 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
13b70 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
13b80 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
13b90 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
13ba0 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
13bb0 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
13bc0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
13bd0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
13be0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
13bf0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
13c00 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
13c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13c20 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
13c30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
13c40 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
13c50 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
13c60 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
13c70 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
13c80 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
13c90 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
13ca0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
13cb0 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
13cc0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
13cd0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
13ce0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
13cf0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
13d00 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  -ops..** </dl>.*
13d10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13d20 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
13d30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13d40 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
13d50 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
13d60 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
13d70 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
13d80 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
13d90 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53   SQLITE_ENABLE_S
13da0 51 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63 65 73  QLLOG pre-proces
13db0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
13dc0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
13dd0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
13de0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
13df0 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
13e00 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
13e10 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
13e20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
13e30 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
13e40 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
13e50 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
13e60 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
13e70 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
13e80 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
13e90 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
13ea0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
13eb0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
13ec0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
13ed0 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
13ee0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
13ef0 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
13f00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
13f10 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
13f20 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
13f30 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
13f40 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
13f50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
13f60 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
13f70 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
13f80 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
13f90 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
13fa0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
13fb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
13fc0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
13fd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
13fe0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
13ff0 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
14000 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
14010 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
14020 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
14030 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
14040 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
14050 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
14060 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
14070 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
14080 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
14090 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
140a0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
140b0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 0a 2a   In this case..*
140c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
140d0 4e 46 49 47 5f 4d 4d 41 50 5f 4c 49 4d 49 54 5d  NFIG_MMAP_LIMIT]
140e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
140f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 4c 49 4d 49  CONFIG_MMAP_LIMI
14100 54 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 73 6f 6c  T.** <dd>The sol
14110 65 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  e argument shoul
14120 64 20 62 65 20 61 20 36 34 2d 62 69 74 20 69 6e  d be a 64-bit in
14130 74 65 67 65 72 20 28 61 6e 20 73 71 6c 69 74 65  teger (an sqlite
14140 33 5f 69 6e 74 36 34 29 20 74 68 61 74 0a 2a 2a  3_int64) that.**
14150 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
14160 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
14170 66 20 62 79 74 65 73 20 6f 66 20 70 72 6f 63 65  f bytes of proce
14180 73 73 20 61 64 64 72 65 73 73 20 73 70 61 63 65  ss address space
14190 20 74 68 61 74 0a 2a 2a 20 73 68 6f 75 6c 64 20   that.** should 
141a0 62 65 20 75 73 65 64 20 66 6f 72 20 61 63 63 65  be used for acce
141b0 73 73 69 6e 67 20 65 61 63 68 20 64 61 74 61 62  ssing each datab
141c0 61 73 65 20 66 69 6c 65 20 75 73 69 6e 67 20 6d  ase file using m
141d0 65 6d 6f 72 79 20 6d 61 70 70 69 6e 67 2e 0a 2a  emory mapping..*
141e0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 73 65  * The default se
141f0 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
14200 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
14210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14220 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
14230 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
14240 6d 6d 61 70 5f 6c 69 6d 69 74 5d 20 63 6f 6d 6d  mmap_limit] comm
14250 61 6e 64 20 6f 72 20 74 68 65 20 22 6d 6d 61 70  and or the "mmap
14260 6c 69 6d 69 74 22 20 71 75 65 72 79 20 70 61 72  limit" query par
14270 61 6d 65 74 65 72 0a 2a 2a 20 6f 6e 20 74 68 65  ameter.** on the
14280 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
14290 77 68 65 6e 20 6f 70 65 6e 69 6e 67 20 74 68 65  when opening the
142a0 20 64 61 74 61 62 61 65 73 20 66 69 6c 65 20 6f   databaes file o
142b0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
142c0 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
142d0 4d 4d 41 50 5f 4c 49 4d 49 54 5d 20 66 69 6c 65  MMAP_LIMIT] file
142e0 20 63 6f 6e 74 72 6f 6c 2e 20 20 54 68 65 20 76   control.  The v
142f0 61 6c 75 65 20 73 65 74 20 68 65 72 65 20 6f 76  alue set here ov
14300 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 63  errides the.** c
14310 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
14320 75 6c 74 20 74 68 61 74 20 69 73 20 73 65 74 20  ult that is set 
14330 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
14340 45 5f 44 45 46 41 55 4c 54 5f 4d 4d 41 50 5f 4c  E_DEFAULT_MMAP_L
14350 49 4d 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  IMIT].** compile
14360 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 49  -time option.  I
14370 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  f the argument t
14380 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
14390 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
143a0 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 6d 61  ** the memory ma
143b0 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74  p limit is set t
143c0 6f 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  o the compile-ti
143d0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  me default..** <
143e0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
143f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
14400 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
14410 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
14420 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14430 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
14440 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
14450 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14460 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
14470 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
14480 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14490 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
144a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
144b0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
144c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
144d0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
144e0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
144f0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
14500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14510 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
14520 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
14530 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
14540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14550 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14560 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
14570 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
14580 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14590 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
145a0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
145b0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
145c0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
145d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
145e0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
145f0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
14600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14610 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
14620 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
14630 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
14640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14650 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14660 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
14670 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14680 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
14690 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
146a0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
146b0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
146c0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
146d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
146e0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
146f0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
14700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14710 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
14720 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
14730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14740 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14750 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
14760 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
14770 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
14780 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
14790 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
147a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
147b0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
147c0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
147d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
147e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
147f0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
14800 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14810 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
14820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14830 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
14840 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14850 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
14860 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14870 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14880 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
14890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
148a0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
148b0 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
148c0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
148d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
148e0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 4c 49 4d 49 54  ONFIG_MMAP_LIMIT
148f0 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
14900 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a  3_int64 */../*.*
14910 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
14920 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
14930 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
14940 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
14950 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
14960 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
14970 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
14980 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
14990 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
149a0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
149b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
149c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
149d0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
149e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
149f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
14a00 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
14a10 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
14a20 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
14a30 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
14a40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
14a50 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
14a60 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
14a70 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
14a80 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
14a90 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
14aa0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
14ab0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
14ac0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
14ad0 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
14ae0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14af0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
14b00 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
14b10 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
14b20 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
14b30 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
14b40 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
14b50 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
14b60 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
14b70 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
14b80 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
14b90 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
14ba0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
14bb0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
14bc0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
14bd0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
14be0 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
14bf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
14c00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
14c10 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
14c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14c30 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
14c40 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
14c50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
14c60 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14c70 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
14c80 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
14c90 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
14ca0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
14cb0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
14cc0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
14cd0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
14ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
14cf0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
14d00 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
14d10 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
14d20 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
14d30 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
14d40 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
14d50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
14d60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14d70 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14d80 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14d90 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
14da0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
14db0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
14dc0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
14dd0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
14de0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
14df0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
14e00 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
14e10 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
14e20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
14e30 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
14e40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
14e50 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
14e60 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14e70 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
14e80 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
14e90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14ea0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
14eb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14ec0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
14ed0 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
14ee0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
14ef0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
14f00 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
14f10 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
14f20 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
14f30 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
14f40 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
14f50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14f60 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
14f70 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
14f80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
14f90 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
14fa0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
14fb0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
14fc0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
14fd0 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
14fe0 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
14ff0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
15000 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
15010 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15020 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
15030 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
15040 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
15050 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
15060 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
15070 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
15080 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
15090 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
150a0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
150b0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
150c0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
150d0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
150e0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
150f0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
15100 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
15110 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
15120 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
15130 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
15140 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
15150 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
15160 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
15170 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
15180 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
15190 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
151a0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
151b0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
151c0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
151d0 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
151e0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
151f0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
15200 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
15210 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
15220 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
15230 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
15240 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
15250 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15260 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
15270 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
15280 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
15290 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
152a0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
152b0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
152c0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
152d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
152e0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
152f0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
15300 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
15310 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
15320 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
15330 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
15340 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15350 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15360 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
15370 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15380 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
15390 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
153a0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
153b0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
153c0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
153d0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
153e0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
153f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15400 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
15410 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
15420 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
15430 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
15440 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
15450 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
15460 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
15470 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
15480 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15490 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
154a0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
154b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
154c0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
154d0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
154e0 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
154f0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
15500 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
15510 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
15520 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
15530 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
15540 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
15550 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
15560 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
15570 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
15580 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
15590 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
155a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
155b0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
155c0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
155d0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
155e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
155f0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
15600 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
15610 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15620 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
15630 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
15640 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
15650 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
15660 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
15670 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
15680 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
15690 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
156a0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
156b0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
156c0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
156d0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
156e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
156f0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
15700 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
15710 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
15720 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
15730 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
15740 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
15750 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
15760 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
15770 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
15780 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
15790 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
157a0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
157b0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
157c0 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
157d0 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
157e0 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
157f0 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
15800 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
15810 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
15820 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
15830 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
15840 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
15850 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
15860 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
15870 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
15880 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
15890 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
158a0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
158b0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
158c0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
158d0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
158e0 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
158f0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
15900 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
15910 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
15920 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
15930 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
15940 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
15950 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
15960 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
15970 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
15980 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
15990 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
159a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
159b0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
159c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
159d0 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69  nt.  ^As of SQLi
159e0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
159f0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a  , this routines.
15a00 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  ** records the l
15a10 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
15a20 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72   of both ordinar
15a30 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69  y tables and [vi
15a40 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a  rtual tables]..*
15a50 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
15a60 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
15a70 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
15a80 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
15a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
15aa0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
15ab0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
15ac0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
15ad0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
15ae0 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
15af0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
15b00 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
15b10 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
15b20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
15b30 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
15b40 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
15b50 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
15b60 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
15b70 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
15b80 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
15b90 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
15ba0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
15bb0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
15bc0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
15bd0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
15be0 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
15bf0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
15c00 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
15c10 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
15c20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
15c30 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
15c40 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
15c50 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
15c60 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
15c70 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
15c80 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
15c90 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
15ca0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
15cb0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
15cc0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
15cd0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
15ce0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
15cf0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
15d00 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
15d10 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
15d20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
15d30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
15d40 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
15d50 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
15d60 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
15d70 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
15d80 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
15d90 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
15da0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
15db0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
15dc0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
15dd0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
15de0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
15df0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
15e00 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
15e10 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
15e20 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
15e30 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
15e40 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
15e50 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
15e60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
15e70 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
15e80 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
15e90 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
15ea0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
15eb0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
15ec0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
15ed0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
15ee0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
15ef0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
15f00 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
15f10 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
15f20 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
15f30 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
15f40 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
15f50 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
15f60 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
15f70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
15f80 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
15f90 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
15fa0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
15fb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
15fc0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
15fd0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
15fe0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
15ff0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
16000 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
16010 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
16020 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
16030 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
16040 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
16050 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
16060 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
16070 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
16080 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
16090 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
160a0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
160b0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
160c0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
160d0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
160e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
160f0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
16100 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
16110 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
16120 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
16130 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
16140 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
16150 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
16160 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
16170 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
16180 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
16190 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
161a0 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
161b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
161c0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
161d0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
161e0 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
161f0 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
16200 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
16210 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
16220 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
16230 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
16240 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
16250 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
16260 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
16270 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
16280 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
16290 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
162a0 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
162b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
162c0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
162d0 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
162e0 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
162f0 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
16300 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
16310 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
16320 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
16330 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
16340 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
16350 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
16360 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
16370 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
16380 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
16390 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
163a0 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
163b0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
163c0 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
163d0 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
163e0 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
163f0 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
16400 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
16410 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
16420 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
16430 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
16440 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
16450 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
16460 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
16470 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
16480 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
16490 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
164a0 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
164b0 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
164c0 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
164d0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
164e0 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
164f0 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
16500 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
16510 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
16520 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
16530 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
16540 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
16550 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
16560 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
16570 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
16580 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
16590 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
165a0 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
165b0 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
165c0 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
165d0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
165e0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
165f0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
16600 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
16610 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
16620 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
16630 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
16640 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
16650 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
16660 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
16670 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
16680 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
16690 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
166a0 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
166b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
166c0 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
166d0 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
166e0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
166f0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
16700 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
16710 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
16720 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
16730 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
16740 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
16750 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
16760 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
16770 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
16780 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
16790 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
167a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
167b0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
167c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
167d0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
167e0 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
167f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
16800 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
16810 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
16820 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
16830 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
16840 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
16850 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
16860 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
16870 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
16880 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
16890 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
168a0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
168b0 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
168c0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
168d0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
168e0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
168f0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
16900 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
16910 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
16920 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
16930 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
16940 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
16950 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
16960 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
16970 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
16980 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
16990 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
169a0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
169b0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
169c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
169d0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
169e0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
169f0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
16a00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
16a10 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
16a20 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
16a30 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
16a40 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
16a50 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
16a60 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
16a70 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
16a80 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
16a90 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
16aa0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
16ab0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
16ac0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
16ad0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
16ae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16af0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
16b00 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
16b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
16b20 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
16b30 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
16b40 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
16b50 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
16b60 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
16b70 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
16b80 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
16b90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
16ba0 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
16bb0 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
16bc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
16bd0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
16be0 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
16bf0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
16c00 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
16c10 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
16c20 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
16c30 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
16c40 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
16c50 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
16c60 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
16c70 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
16c80 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
16c90 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
16ca0 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
16cb0 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
16cc0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
16cd0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
16ce0 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
16cf0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
16d00 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
16d10 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
16d20 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
16d30 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
16d40 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
16d50 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
16d60 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
16d70 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
16d80 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
16d90 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
16da0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
16db0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
16dc0 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
16dd0 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
16de0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
16df0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
16e00 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
16e10 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
16e20 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
16e30 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
16e40 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
16e50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
16e60 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
16e70 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
16e80 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
16e90 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
16ea0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
16eb0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
16ec0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
16ed0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
16ee0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
16ef0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
16f00 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
16f10 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
16f20 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
16f30 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
16f40 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
16f50 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
16f60 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
16f70 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
16f80 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
16f90 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
16fa0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
16fb0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
16fc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
16fd0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
16fe0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
16ff0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17000 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
17010 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
17020 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
17030 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
17040 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
17050 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
17060 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
17070 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
17080 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
17090 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
170a0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
170b0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
170c0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
170d0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
170e0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
170f0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
17100 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
17110 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
17120 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
17130 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
17140 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
17150 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
17160 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
17170 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
17180 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
17190 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
171a0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
171b0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
171c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
171d0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
171e0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
171f0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
17200 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17210 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
17220 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
17230 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
17240 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
17250 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
17260 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17270 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
17280 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
17290 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
172a0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
172b0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
172c0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
172d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
172e0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
172f0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
17300 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
17310 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
17320 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
17330 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
17340 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
17350 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
17360 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
17370 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
17380 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
17390 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
173a0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
173b0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
173c0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
173d0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
173e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
173f0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
17400 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
17410 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
17420 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
17430 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
17440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17450 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
17460 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
17470 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
17480 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
17490 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
174a0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
174b0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
174c0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
174d0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
174e0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
174f0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
17500 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
17510 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
17520 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17530 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
17540 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
17550 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
17560 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
17570 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
17580 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
17590 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
175a0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
175b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
175c0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
175d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
175e0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
175f0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
17600 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
17610 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
17620 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
17630 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
17640 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
17650 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
17660 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
17670 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
17680 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
17690 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
176a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
176b0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
176c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
176d0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
176e0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
176f0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
17700 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
17710 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
17720 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17730 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
17740 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
17750 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
17760 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
17770 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
17780 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
17790 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
177a0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
177b0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
177c0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
177d0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
177e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
177f0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
17800 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
17810 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
17820 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
17830 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
17840 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
17850 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
17860 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
17870 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
17880 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
17890 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
178a0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
178b0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
178c0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
178d0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
178e0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
178f0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
17900 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
17910 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
17920 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
17930 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
17940 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
17950 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
17960 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
17970 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
17980 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
17990 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
179a0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
179b0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
179c0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
179d0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
179e0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
179f0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
17a00 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
17a10 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
17a20 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
17a30 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
17a40 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
17a50 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
17a60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
17a70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
17a80 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
17a90 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
17aa0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
17ab0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
17ac0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
17ad0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
17ae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
17af0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
17b00 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
17b10 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
17b20 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
17b30 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
17b40 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
17b50 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
17b60 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
17b70 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
17b80 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
17b90 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
17ba0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
17bb0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
17bc0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
17bd0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
17be0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
17bf0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
17c00 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
17c10 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
17c20 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
17c30 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
17c40 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
17c50 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
17c60 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
17c70 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
17c80 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
17c90 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
17ca0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
17cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
17cc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
17cd0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
17ce0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
17cf0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
17d00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
17d10 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
17d20 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
17d30 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
17d40 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
17d50 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
17d60 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
17d70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
17d80 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
17d90 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
17da0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
17db0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
17dc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17dd0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
17de0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
17df0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
17e00 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
17e10 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
17e20 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17e30 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
17e40 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
17e50 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
17e60 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
17e70 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
17e80 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
17e90 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
17ea0 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
17eb0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
17ec0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
17ed0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
17ee0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
17ef0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
17f00 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
17f10 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
17f20 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
17f30 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
17f40 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
17f50 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
17f60 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
17f70 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
17f80 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
17f90 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
17fa0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
17fb0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17fc0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
17fd0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
17fe0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
17ff0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
18000 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
18010 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
18020 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18030 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
18040 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
18050 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
18060 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
18070 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
18080 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
18090 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
180a0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
180b0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
180c0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
180d0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
180e0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
180f0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
18100 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
18110 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
18120 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18130 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
18140 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
18150 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
18160 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
18170 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
18180 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
18190 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
181a0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
181b0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
181c0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
181d0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
181e0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
181f0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
18200 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
18210 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
18220 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
18230 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
18240 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
18250 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
18260 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
18270 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
18280 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
18290 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
182a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
182b0 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
182c0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
182d0 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
182e0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
182f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
18300 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
18310 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
18320 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
18330 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
18340 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
18350 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
18360 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
18370 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
18380 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
18390 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
183a0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
183b0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
183c0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
183d0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
183e0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
183f0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
18400 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
18410 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
18420 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
18430 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
18440 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
18450 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
18460 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
18470 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
18480 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
18490 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
184a0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
184b0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
184c0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
184d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
184e0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
184f0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
18500 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
18510 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
18520 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
18530 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
18540 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
18550 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
18560 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
18570 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
18580 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
18590 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
185a0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
185b0 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
185c0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
185d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
185e0 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
185f0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
18600 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
18610 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
18620 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
18630 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
18640 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
18650 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
18660 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
18670 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
18680 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
18690 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
186a0 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
186b0 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
186c0 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
186d0 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
186e0 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
186f0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
18700 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
18710 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
18720 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
18730 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
18740 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
18750 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
18760 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
18770 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
18780 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
18790 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
187a0 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
187b0 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
187c0 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
187d0 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
187e0 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
187f0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
18800 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18810 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
18820 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
18830 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
18840 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
18850 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
18860 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
18870 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
18880 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
18890 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
188a0 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
188b0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
188c0 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
188d0 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
188e0 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
188f0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
18900 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
18910 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
18920 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
18930 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
18940 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
18950 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
18960 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
18970 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
18980 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
18990 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
189a0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
189b0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
189c0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
189d0 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
189e0 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
189f0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
18a00 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
18a10 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
18a20 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
18a30 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
18a40 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
18a50 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
18a60 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
18a70 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
18a80 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
18a90 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
18aa0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
18ab0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
18ac0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
18ad0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18ae0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
18af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18b00 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
18b10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18b20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
18b30 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
18b40 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
18b50 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
18b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18b70 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
18b80 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
18b90 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
18ba0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
18bb0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
18bc0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
18bd0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
18be0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
18bf0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
18c00 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
18c10 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
18c20 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
18c30 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
18c40 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
18c50 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
18c60 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
18c70 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
18c80 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
18c90 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
18ca0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
18cb0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
18cc0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
18cd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18ce0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
18cf0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
18d00 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
18d10 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
18d20 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
18d30 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
18d40 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
18d50 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
18d60 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
18d70 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
18d80 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
18d90 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
18da0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
18db0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
18dc0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18dd0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
18de0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
18df0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
18e00 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
18e10 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
18e20 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18e30 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
18e40 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
18e50 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
18e60 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
18e70 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
18e80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
18e90 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
18ea0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
18eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18ec0 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
18ed0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
18ee0 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
18ef0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
18f00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
18f10 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
18f20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
18f30 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
18f40 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
18f50 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
18f60 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
18f70 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
18f80 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
18f90 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
18fa0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
18fb0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
18fc0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
18fd0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
18fe0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
18ff0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
19000 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
19010 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
19020 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
19030 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
19040 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
19050 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
19060 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
19070 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
19080 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
19090 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
190a0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
190b0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
190c0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
190d0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
190e0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
190f0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
19100 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
19110 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
19120 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
19130 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
19140 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
19150 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
19160 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
19170 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
19180 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
19190 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
191a0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
191b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
191c0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
191d0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
191e0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
191f0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
19200 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
19210 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
19220 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
19230 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
19240 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
19250 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
19260 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
19270 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
19280 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
19290 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
192a0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
192b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
192c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
192d0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
192e0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
192f0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
19300 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
19310 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
19320 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
19330 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
19340 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
19350 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
19360 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
19370 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
19380 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
19390 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
193a0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
193b0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
193c0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
193d0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
193e0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
193f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19400 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
19410 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
19420 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
19430 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19440 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
19450 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
19460 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
19470 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
19480 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
19490 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
194a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
194b0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
194c0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
194d0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
194e0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
194f0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
19500 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
19510 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
19520 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
19530 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
19540 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
19550 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
19560 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
19570 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
19580 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19590 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
195a0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
195b0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
195c0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
195d0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
195e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
195f0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
19600 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19610 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
19620 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19630 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
19640 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19650 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
19660 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19670 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
19680 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
19690 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
196a0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
196b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
196c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
196d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
196e0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
196f0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
19700 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
19710 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
19720 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
19730 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
19740 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
19750 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
19760 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
19770 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
19780 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
19790 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
197a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
197b0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
197c0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
197d0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
197e0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
197f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
19800 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
19810 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
19820 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
19830 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
19840 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
19850 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
19860 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
19870 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
19880 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
19890 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
198a0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
198b0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
198c0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
198d0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
198e0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
198f0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
19900 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
19910 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
19920 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
19930 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
19940 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
19950 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
19960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
19970 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
19980 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
19990 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
199a0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
199b0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
199c0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
199d0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
199e0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
199f0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
19a00 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
19a10 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
19a20 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
19a30 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
19a40 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
19a50 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
19a60 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
19a70 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
19a80 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
19a90 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
19aa0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
19ab0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
19ac0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
19ad0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
19ae0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
19af0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
19b00 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
19b10 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
19b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
19b30 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
19b40 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
19b50 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
19b60 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
19b70 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
19b80 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
19b90 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
19ba0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
19bb0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
19bc0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
19bd0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
19be0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
19bf0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
19c00 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
19c10 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
19c20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
19c30 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
19c40 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
19c50 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
19c60 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
19c70 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
19c80 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
19c90 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
19ca0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
19cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19cc0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
19cd0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
19ce0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
19cf0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19d00 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
19d10 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
19d20 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
19d30 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
19d40 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
19d50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19d60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
19d70 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
19d80 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
19d90 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
19da0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
19db0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
19dc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
19dd0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
19de0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
19df0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
19e00 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
19e10 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
19e20 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
19e30 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
19e40 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
19e50 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
19e60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
19e70 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
19e80 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
19e90 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
19ea0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
19eb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
19ec0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
19ed0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
19ee0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
19ef0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
19f00 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
19f10 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
19f20 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
19f30 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
19f40 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
19f50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
19f60 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
19f70 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
19f80 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
19f90 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
19fa0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
19fb0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
19fc0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
19fd0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
19fe0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
19ff0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1a000 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1a010 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1a020 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1a030 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1a040 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1a050 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1a060 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1a070 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1a080 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1a090 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1a0a0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1a0b0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1a0c0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1a0d0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1a0e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1a0f0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1a100 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1a110 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1a120 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1a130 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1a140 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1a150 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1a160 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1a170 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1a180 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1a190 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1a1a0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1a1b0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1a1c0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1a1d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a1e0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1a1f0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1a200 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1a210 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1a220 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1a230 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1a240 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1a250 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1a260 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1a270 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1a280 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1a290 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1a2a0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1a2b0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1a2c0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1a2d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1a2e0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1a2f0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1a300 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1a310 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1a320 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1a330 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1a340 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1a350 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1a360 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1a370 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1a380 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1a390 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1a3a0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1a3b0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1a3c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1a3d0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1a3e0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1a3f0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1a400 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
1a410 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1a420 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1a430 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1a440 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1a450 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1a460 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1a470 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1a480 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1a490 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1a4a0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1a4b0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1a4c0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1a4d0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1a4e0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1a4f0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1a500 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1a510 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1a520 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1a530 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1a540 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1a550 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1a560 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1a570 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1a580 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1a590 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1a5a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a5b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1a5c0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1a5d0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1a5e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a5f0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1a600 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1a610 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1a620 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1a630 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1a640 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1a650 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1a660 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1a670 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1a680 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1a690 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1a6a0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1a6b0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1a6c0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1a6d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a6e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1a6f0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1a700 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1a710 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1a720 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1a730 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1a740 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1a750 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1a760 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a770 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a780 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1a790 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1a7a0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1a7b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a7c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1a7d0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1a7e0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1a7f0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1a800 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1a810 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1a820 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1a830 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a840 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1a850 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1a860 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1a870 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1a880 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a890 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1a8a0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1a8b0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1a8c0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1a8d0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1a8e0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1a8f0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1a900 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1a910 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1a920 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1a930 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1a940 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1a950 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1a960 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1a970 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1a980 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1a990 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1a9a0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1a9b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1a9c0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1a9d0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1a9e0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1a9f0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1aa00 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1aa10 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1aa20 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1aa30 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1aa40 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1aa50 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1aa60 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1aa70 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1aa80 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1aa90 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1aaa0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1aab0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1aac0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1aad0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1aae0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1aaf0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1ab00 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1ab10 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1ab20 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1ab30 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1ab40 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1ab50 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1ab60 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1ab70 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1ab80 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1ab90 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1aba0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1abb0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1abc0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1abd0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1abe0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1abf0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1ac00 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1ac10 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1ac20 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1ac30 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1ac40 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1ac50 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1ac60 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1ac70 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1ac80 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1ac90 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1aca0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1acb0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1acc0 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1acd0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1ace0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1acf0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1ad00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ad10 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1ad20 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1ad30 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1ad40 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1ad50 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1ad60 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1ad70 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1ad80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1ad90 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1ada0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1adb0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1adc0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1add0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1ade0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1adf0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1ae00 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1ae10 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1ae20 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1ae30 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1ae40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ae50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1ae60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1ae70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1ae80 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1ae90 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1aea0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1aeb0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1aec0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1aed0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1aee0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1aef0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1af00 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1af10 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1af20 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1af30 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1af40 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1af50 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1af60 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1af70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1af80 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1af90 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
1afa0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1afb0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1afc0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1afd0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1afe0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1aff0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1b000 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1b010 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1b020 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1b030 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1b040 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1b050 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1b060 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1b070 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1b080 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1b090 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1b0a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1b0b0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1b0c0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1b0d0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1b0e0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1b0f0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1b100 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1b110 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1b120 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1b130 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1b140 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1b150 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1b160 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1b170 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1b180 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1b190 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1b1a0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1b1b0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1b1c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1b1d0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1b1e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1b1f0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1b200 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1b210 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1b220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b230 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1b240 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1b250 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1b260 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1b270 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1b280 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1b290 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1b2a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1b2b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1b2c0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1b2d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1b2e0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1b2f0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1b300 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1b310 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1b320 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1b330 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1b340 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1b350 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1b360 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1b370 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1b380 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1b390 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1b3a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1b3b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1b3c0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1b3d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1b3e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b3f0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1b400 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1b410 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1b420 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1b430 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1b440 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1b450 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1b460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1b470 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1b480 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1b490 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1b4a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1b4b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1b4c0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1b4d0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1b4e0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1b4f0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1b500 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1b510 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1b520 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1b530 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1b540 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1b550 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1b560 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1b570 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1b580 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1b590 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1b5a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b5b0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1b5c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1b5d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1b5e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1b5f0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1b600 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1b610 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1b620 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1b630 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1b640 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1b650 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1b660 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1b670 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1b680 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1b690 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1b6a0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1b6b0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1b6c0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1b6d0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1b6e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1b6f0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1b700 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1b710 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1b720 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1b730 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1b740 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1b750 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1b760 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1b770 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1b780 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1b790 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1b7a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1b7b0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1b7c0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1b7d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1b7e0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1b7f0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1b800 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1b810 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1b820 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1b830 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1b840 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1b850 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1b860 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1b870 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1b880 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1b890 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1b8a0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1b8b0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1b8c0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1b8d0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1b8e0 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1b8f0 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1b900 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1b910 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1b920 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1b930 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1b940 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1b950 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1b960 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1b970 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1b980 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1b990 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1b9a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1b9b0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1b9c0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1b9d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1b9e0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1b9f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1ba00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1ba10 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1ba20 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1ba30 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1ba40 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1ba50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1ba60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1ba70 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1ba80 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1ba90 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1baa0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1bab0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1bac0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1bad0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1bae0 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1baf0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1bb00 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1bb10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1bb20 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1bb30 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
1bb40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
1bb50 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
1bb60 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1bb70 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1bb80 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1bb90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bba0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1bbb0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1bbc0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1bbd0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1bbe0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1bbf0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1bc00 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1bc10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1bc20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1bc30 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1bc40 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1bc50 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1bc60 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1bc70 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1bc80 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1bc90 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1bca0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1bcb0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1bcc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1bcd0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1bce0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1bcf0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1bd00 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1bd10 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1bd20 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1bd30 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1bd40 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1bd50 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1bd60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1bd70 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1bd80 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1bd90 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1bda0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1bdb0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1bdc0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1bdd0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1bde0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1bdf0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1be00 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1be10 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1be20 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1be30 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1be40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1be50 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1be60 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1be70 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1be80 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1be90 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1bea0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1beb0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1bec0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1bed0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1bee0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1bef0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1bf00 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1bf10 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1bf20 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1bf30 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1bf40 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1bf50 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1bf60 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1bf70 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1bf80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1bf90 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1bfa0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1bfb0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1bfc0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1bfd0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1bfe0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1bff0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1c000 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1c010 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1c020 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1c030 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1c040 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1c050 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1c060 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1c070 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1c080 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1c090 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1c0a0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1c0b0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1c0c0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1c0d0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1c0e0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1c0f0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1c100 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1c110 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1c120 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1c130 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1c140 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1c150 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1c160 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1c170 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1c180 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1c190 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1c1a0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1c1b0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1c1c0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1c1d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1c1e0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1c1f0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1c200 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1c210 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1c220 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
1c230 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
1c240 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
1c250 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
1c260 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
1c270 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
1c280 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
1c290 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1c2a0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
1c2b0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1c2c0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
1c2d0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1c2e0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
1c2f0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
1c300 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
1c310 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
1c320 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
1c330 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
1c340 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
1c350 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
1c360 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
1c370 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
1c380 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
1c390 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1c3a0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1c3b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1c3c0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1c3d0 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1c3e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1c3f0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1c400 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1c410 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1c420 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1c430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c440 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1c450 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1c460 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1c470 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1c480 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1c490 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1c4a0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1c4b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1c4c0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1c4d0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1c4e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1c4f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c500 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1c510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1c520 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1c530 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1c540 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1c550 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1c560 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1c570 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1c580 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1c590 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1c5a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1c5b0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1c5c0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1c5d0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1c5e0 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1c5f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1c600 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1c610 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1c620 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1c630 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1c640 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1c650 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1c660 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1c670 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1c680 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1c690 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1c6a0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1c6b0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1c6c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1c6d0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1c6e0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1c6f0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1c700 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1c710 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1c720 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1c730 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1c740 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1c750 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1c760 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1c770 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1c780 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1c790 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1c7a0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1c7b0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1c7c0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1c7d0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1c7e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c7f0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1c800 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1c810 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1c820 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1c830 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1c840 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1c850 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1c860 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c870 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1c880 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1c890 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1c8a0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1c8b0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1c8c0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1c8d0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1c8e0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1c8f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1c900 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1c910 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c920 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1c930 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1c940 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c950 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1c960 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1c970 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1c980 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1c990 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1c9a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1c9b0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1c9c0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1c9d0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1c9e0 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1c9f0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1ca00 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1ca10 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1ca20 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1ca30 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1ca40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1ca50 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1ca60 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1ca70 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1ca80 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1ca90 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1caa0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1cab0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1cac0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1cad0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1cae0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1caf0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1cb00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1cb10 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1cb20 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1cb30 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1cb40 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1cb50 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1cb60 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1cb70 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1cb80 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1cb90 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1cba0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1cbb0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1cbc0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1cbd0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1cbe0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1cbf0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1cc00 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1cc10 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1cc20 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1cc30 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1cc40 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1cc50 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1cc60 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1cc70 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1cc80 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1cc90 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1cca0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1ccb0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1ccc0 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1ccd0 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1cce0 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1ccf0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1cd00 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1cd10 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1cd20 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1cd30 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1cd40 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1cd50 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1cd60 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1cd70 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1cd80 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1cd90 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1cda0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1cdb0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1cdc0 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1cdd0 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1cde0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1cdf0 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1ce00 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1ce10 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1ce20 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1ce30 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1ce40 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1ce50 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1ce60 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1ce70 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1ce80 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1ce90 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1cea0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1ceb0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1cec0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1ced0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1cee0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1cef0 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1cf00 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1cf10 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1cf20 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1cf30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1cf40 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1cf50 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1cf60 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1cf70 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1cf80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1cf90 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1cfa0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1cfb0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1cfc0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1cfd0 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1cfe0 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1cff0 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1d000 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1d010 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1d020 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1d030 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1d040 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1d050 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1d060 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1d070 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1d080 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1d090 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1d0a0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1d0b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d0c0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1d0d0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1d0e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1d0f0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1d100 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1d110 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1d120 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1d130 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1d140 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1d150 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1d160 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1d170 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1d180 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1d190 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1d1a0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1d1b0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1d1c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d1d0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1d1e0 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1d1f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1d200 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1d210 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d220 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d230 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1d240 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1d250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d260 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1d270 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1d280 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1d290 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1d2a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d2b0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1d2c0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1d2d0 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1d2e0 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1d2f0 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1d300 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d310 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1d320 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1d330 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1d340 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1d350 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1d360 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1d370 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1d380 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1d390 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1d3a0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1d3b0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1d3c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d3d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1d3e0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1d3f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1d400 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1d410 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1d420 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1d430 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1d440 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1d450 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1d460 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1d470 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1d480 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1d490 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1d4a0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1d4b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d4c0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1d4d0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1d4e0 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1d4f0 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
1d500 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d510 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
1d520 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
1d530 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
1d540 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1d550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1d560 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
1d570 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
1d580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d590 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
1d5a0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1d5b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1d5c0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1d5d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d5e0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
1d5f0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
1d600 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
1d610 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
1d620 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
1d630 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
1d640 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
1d650 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
1d660 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
1d670 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
1d680 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1d690 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1d6a0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1d6b0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1d6c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1d6d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
1d6e0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
1d6f0 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53  lso used as a [S
1d700 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c  QLITE_ROLLBACK |
1d710 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a   return code].**
1d720 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1d730 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1d740 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1d750 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1d760 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1d770 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1d780 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1d790 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1d7a0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1d7b0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1d7c0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1d7d0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1d7e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1d7f0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1d800 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1d810 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1d820 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1d830 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1d840 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1d850 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1d860 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1d870 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1d880 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1d890 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1d8a0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1d8b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1d8c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1d8d0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1d8e0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1d8f0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1d900 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1d910 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1d920 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1d930 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1d940 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d950 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1d960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1d970 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1d980 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1d990 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1d9a0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1d9b0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1d9c0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1d9d0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1d9e0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1d9f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1da00 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1da10 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1da20 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1da30 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1da40 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1da50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1da60 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1da70 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1da80 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1da90 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1daa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1dab0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1dac0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1dad0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1dae0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1daf0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1db00 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1db10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1db20 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1db30 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1db40 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1db50 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1db60 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1db70 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1db80 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1db90 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1dba0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1dbb0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1dbc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1dbd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1dbe0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1dbf0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1dc00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1dc10 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1dc20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1dc30 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1dc40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1dc50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1dc60 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1dc70 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1dc80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1dc90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1dca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1dcb0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1dcc0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1dcd0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1dce0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1dcf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1dd00 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1dd10 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1dd20 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1dd30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1dd40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1dd50 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1dd60 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1dd70 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1dd80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1dd90 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1dda0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1ddb0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1ddc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ddd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1dde0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ddf0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1de00 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1de10 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1de20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1de30 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1de40 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1de50 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1de60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1de70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1de80 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1de90 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1dea0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1deb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1dec0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ded0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1dee0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1def0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1df00 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1df10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1df20 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1df30 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1df40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1df50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1df60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1df70 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1df80 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1df90 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1dfa0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dfb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dfc0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1dfd0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1dfe0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dff0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e010 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1e020 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1e030 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1e040 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e050 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e060 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1e070 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1e080 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1e090 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e0a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e0b0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1e0c0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1e0d0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1e0e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e100 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1e110 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1e120 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1e130 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1e150 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1e160 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1e170 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e180 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1e1a0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1e1b0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1e1c0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1e1d0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1e1e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1e1f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e200 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1e210 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1e220 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1e230 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1e240 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1e250 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1e260 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1e270 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e280 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1e290 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1e2a0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1e2b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1e2c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e2d0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1e2e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1e2f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e300 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1e310 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1e320 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1e330 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1e340 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1e350 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e360 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e370 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1e380 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1e390 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1e3a0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1e3b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e3c0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1e3d0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1e3e0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1e3f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e400 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e410 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1e420 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1e430 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e440 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e450 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e460 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1e470 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1e480 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e490 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e4a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e4b0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1e4c0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1e4d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e4e0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1e4f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e500 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1e510 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1e520 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1e530 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1e540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e550 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1e560 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1e570 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1e580 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1e590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e5a0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1e5b0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1e5c0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1e5d0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1e5e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e5f0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1e600 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1e610 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
1e620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e630 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1e640 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1e650 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1e660 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1e670 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1e680 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1e690 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1e6a0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1e6b0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1e6c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1e6d0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1e6e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1e6f0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1e700 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1e710 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1e720 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1e730 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1e740 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1e750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1e760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e770 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1e780 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1e790 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1e7a0 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1e7b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1e7c0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1e7d0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1e7e0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1e7f0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1e800 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1e810 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1e820 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1e830 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1e840 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1e850 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1e860 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1e870 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1e880 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1e890 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1e8a0 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
1e8b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e8c0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1e8d0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1e8e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1e8f0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1e900 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1e910 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1e920 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1e930 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1e940 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1e950 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1e960 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1e970 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1e980 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1e990 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
1e9a0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1e9b0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
1e9c0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
1e9d0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
1e9e0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
1e9f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
1ea00 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
1ea10 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
1ea20 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
1ea30 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
1ea40 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
1ea50 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
1ea60 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
1ea70 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1ea80 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
1ea90 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
1eaa0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
1eab0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
1eac0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
1ead0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1eae0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
1eaf0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
1eb00 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
1eb10 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1eb20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
1eb30 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
1eb40 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
1eb50 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
1eb60 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
1eb70 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
1eb80 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
1eb90 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1eba0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
1ebb0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
1ebc0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
1ebd0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1ebe0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
1ebf0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1ec00 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
1ec10 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
1ec20 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
1ec30 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1ec40 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
1ec50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
1ec60 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
1ec70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
1ec80 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
1ec90 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1eca0 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1ecb0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
1ecc0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1ecd0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
1ece0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1ecf0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
1ed00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ed10 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
1ed20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1ed30 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1ed40 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1ed50 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1ed60 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1ed70 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
1ed80 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1ed90 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
1eda0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
1edb0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1edc0 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
1edd0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
1ede0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1edf0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1ee00 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1ee10 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1ee20 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1ee30 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1ee40 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1ee50 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  ck X..**.** ^Onl
1ee60 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
1ee70 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
1ee80 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
1ee90 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
1eea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1eeb0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
1eec0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
1eed0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
1eee0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
1eef0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
1ef00 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
1ef10 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
1ef20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
1ef30 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1ef40 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
1ef50 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
1ef60 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
1ef70 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
1ef80 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
1ef90 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1efa0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1efb0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
1efc0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
1efd0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
1efe0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
1eff0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
1f000 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
1f010 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
1f020 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
1f030 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f040 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1f050 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1f060 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1f070 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1f080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1f090 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1f0a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1f0b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1f0c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f0d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f0e0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1f0f0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1f100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f110 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1f120 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1f130 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1f140 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
1f150 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1f160 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1f170 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
1f180 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
1f190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
1f1a0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
1f1b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
1f1c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1f1d0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
1f1e0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
1f1f0 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
1f200 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
1f210 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
1f220 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1f230 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
1f240 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
1f250 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1f260 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1f270 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
1f280 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1f290 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
1f2a0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
1f2b0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
1f2c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f2d0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
1f2e0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
1f2f0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
1f300 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
1f310 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
1f320 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
1f330 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
1f340 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f350 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
1f360 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1f370 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
1f380 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
1f390 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
1f3a0 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
1f3b0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1f3c0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
1f3d0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
1f3e0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
1f3f0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
1f400 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
1f410 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
1f420 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
1f430 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1f440 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1f450 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
1f460 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1f470 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1f480 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
1f490 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1f4a0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
1f4b0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
1f4c0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
1f4d0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
1f4e0 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
1f4f0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
1f500 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
1f510 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
1f520 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
1f530 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
1f540 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
1f550 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
1f560 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1f570 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c  open_v2() is cal
1f580 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
1f590 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1f5a0 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71  byte order if sq
1f5b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
1f5c0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
1f5d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
1f5e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
1f5f0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
1f600 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
1f610 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1f620 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f630 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
1f640 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
1f650 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
1f660 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
1f670 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
1f680 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
1f690 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1f6a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f6b0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
1f6c0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
1f6d0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
1f6e0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
1f6f0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
1f700 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
1f710 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
1f720 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
1f730 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f740 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
1f750 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
1f760 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
1f770 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
1f780 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
1f790 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
1f7a0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
1f7b0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
1f7c0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
1f7d0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
1f7e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1f7f0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1f800 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
1f810 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f820 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
1f830 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1f840 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
1f850 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
1f860 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1f870 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
1f880 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1f890 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
1f8a0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
1f8b0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
1f8c0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
1f8d0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
1f8e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1f8f0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1f900 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1f910 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
1f920 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1f930 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1f940 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1f950 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1f960 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
1f970 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
1f980 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1f990 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1f9a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1f9b0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
1f9c0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
1f9d0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
1f9e0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
1f9f0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1fa00 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1fa10 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1fa20 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1fa30 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
1fa40 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
1fa50 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1fa60 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1fa70 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1fa80 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
1fa90 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
1faa0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
1fab0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
1fac0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
1fad0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
1fae0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1faf0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1fb00 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
1fb10 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
1fb20 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
1fb30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1fb40 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
1fb50 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
1fb60 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1fb70 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
1fb80 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
1fb90 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
1fba0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
1fbb0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
1fbc0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
1fbd0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1fbe0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
1fbf0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1fc00 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1fc10 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1fc20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fc30 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1fc40 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1fc50 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1fc60 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1fc70 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1fc80 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1fc90 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1fca0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1fcb0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
1fcc0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1fcd0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1fce0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
1fcf0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fd00 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
1fd10 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1fd20 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1fd30 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
1fd40 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
1fd50 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
1fd60 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
1fd70 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1fd80 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1fd90 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1fda0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1fdb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1fdc0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
1fdd0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
1fde0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1fdf0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
1fe00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1fe10 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
1fe20 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
1fe30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1fe40 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1fe50 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
1fe60 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1fe70 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
1fe80 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1fe90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
1fea0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
1feb0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
1fec0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
1fed0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
1fee0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
1fef0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1ff00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ff10 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1ff20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1ff30 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
1ff40 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
1ff50 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1ff60 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
1ff70 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1ff80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
1ff90 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
1ffa0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1ffb0 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
1ffc0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
1ffd0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1ffe0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
1fff0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
20000 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
20010 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
20020 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
20030 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
20040 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
20050 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
20060 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
20070 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
20080 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
20090 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
200a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
200b0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
200c0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
200d0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
200e0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
200f0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
20100 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
20110 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
20120 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
20130 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
20140 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
20150 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
20160 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
20170 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
20180 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
20190 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
201a0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
201b0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
201c0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
201d0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
201e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
201f0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
20200 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
20210 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
20220 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
20230 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
20240 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
20250 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
20260 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
20270 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
20280 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
20290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
202a0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
202b0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
202c0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
202d0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
202e0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
202f0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
20300 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
20310 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
20320 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
20330 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
20340 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
20350 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
20360 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
20370 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
20380 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
20390 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
203a0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
203b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
203c0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
203d0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
203e0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
203f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
20400 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
20410 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
20420 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
20430 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
20440 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
20450 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20460 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
20470 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
20480 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
20490 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
204a0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
204b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
204c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
204d0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
204e0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
204f0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
20500 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
20510 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
20520 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
20530 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
20540 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
20550 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
20560 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
20570 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
20580 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
20590 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
205a0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
205b0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
205c0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
205d0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
205e0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
205f0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
20600 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
20610 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
20620 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
20630 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
20640 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
20650 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
20660 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
20670 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
20680 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
20690 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
206a0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
206b0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
206c0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
206d0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
206e0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
206f0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
20700 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
20710 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
20720 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
20730 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
20740 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
20750 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
20760 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
20770 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
20780 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
20790 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
207a0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
207b0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
207c0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
207d0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
207e0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
207f0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
20800 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
20810 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
20820 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
20830 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
20840 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
20850 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
20860 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
20870 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
20880 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a   (e.g. "C:")..**
20890 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
208a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
208b0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
208c0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
208d0 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
208e0 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
208f0 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
20900 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
20910 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
20920 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
20930 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
20940 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  on]..** SQLite i
20950 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f  nterprets the fo
20960 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75  llowing three qu
20970 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
20980 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
20990 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
209a0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
209b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
209c0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
209d0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
209e0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
209f0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
20a00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
20a10 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
20a20 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
20a30 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
20a40 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
20a50 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
20a60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
20a70 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
20a80 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
20a90 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
20aa0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
20ab0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
20ac0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
20ad0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
20ae0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20af0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
20b00 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
20b10 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
20b20 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
20b30 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
20b40 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
20b50 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
20b60 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
20b70 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
20b80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
20b90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
20ba0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
20bb0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
20bc0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
20bd0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
20be0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
20bf0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
20c00 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
20c10 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
20c20 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
20c30 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
20c40 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
20c50 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
20c60 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
20c70 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20c80 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
20c90 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
20ca0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
20cb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20cc0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
20cd0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
20ce0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
20cf0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
20d00 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
20d10 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
20d20 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
20d30 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
20d40 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20d50 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
20d60 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
20d70 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
20d80 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
20d90 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
20da0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
20db0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
20dc0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
20dd0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
20de0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
20df0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
20e00 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
20e10 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
20e20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
20e30 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
20e40 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
20e50 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
20e60 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
20e70 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
20e80 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
20e90 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
20ea0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
20eb0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
20ec0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
20ed0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
20ee0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
20ef0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
20f00 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
20f10 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
20f20 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
20f30 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
20f40 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
20f50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
20f60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
20f70 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
20f80 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
20f90 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
20fa0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
20fb0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
20fc0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
20fd0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
20fe0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
20ff0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
21000 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
21010 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
21020 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
21030 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
21040 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
21050 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
21060 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
21070 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
21080 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
21090 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
210a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
210b0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
210c0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
210d0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
210e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
210f0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
21100 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
21110 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
21120 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
21130 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
21140 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
21150 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
21160 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
21170 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
21180 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
21190 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
211a0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20  DCACHE flag..** 
211b0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
211c0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
211d0 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
211e0 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
211f0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
21200 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
21210 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
21220 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
21230 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
21240 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
21250 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
21260 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
21270 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
21280 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
21290 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
212a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
212b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
212c0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
212d0 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
212e0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
212f0 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
21300 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
21310 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
21320 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
21330 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
21340 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
21350 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21360 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
21370 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
21380 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
21390 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
213a0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
213b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
213c0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
213d0 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
213e0 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
213f0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
21400 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
21410 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
21420 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
21430 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
21440 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
21450 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
21460 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21470 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
21480 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
21490 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
214a0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
214b0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
214c0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
214d0 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
214e0 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
214f0 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
21500 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
21510 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
21520 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
21530 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
21540 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
21550 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
21560 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
21570 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
21580 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
21590 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
215a0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
215b0 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
215c0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
215d0 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
215e0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
215f0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
21600 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
21610 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
21620 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
21630 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
21640 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
21650 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
21660 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
21670 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
21680 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
21690 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
216a0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
216b0 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
216c0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
216d0 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
216e0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
216f0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
21700 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
21710 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
21720 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
21730 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
21740 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
21750 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
21760 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
21770 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20  nolock <td>.**  
21780 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21790 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
217a0 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
217b0 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
217c0 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74  x-nolock"..** <t
217d0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
217e0 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
217f0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
21800 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
21810 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
21820 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
21830 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
21840 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
21850 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
21860 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21870 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
21880 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
21890 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
218a0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
218b0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
218c0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
218d0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
218e0 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
218f0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
21900 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
21910 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
21920 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
21930 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
21940 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
21950 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
21960 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
21970 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
21980 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
21990 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
219a0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
219b0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
219c0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
219d0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
219e0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
219f0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
21a00 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
21a10 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
21a20 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
21a30 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
21a40 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
21a50 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
21a60 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
21a70 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
21a80 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
21a90 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
21aa0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
21ab0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
21ac0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
21ad0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
21ae0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21af0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
21b00 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
21b10 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
21b20 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
21b30 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
21b40 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
21b50 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
21b60 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
21b70 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
21b80 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
21b90 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
21ba0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
21bb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
21bc0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
21bd0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
21be0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
21bf0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
21c00 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
21c10 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
21c20 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
21c30 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
21c40 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
21c50 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
21c60 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
21c70 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
21c80 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
21c90 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
21ca0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21cb0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
21cc0 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
21cd0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
21ce0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
21cf0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
21d00 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
21d10 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
21d20 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
21d30 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
21d40 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
21d50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21d60 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
21d70 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
21d80 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21d90 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
21da0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
21db0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
21dc0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
21dd0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
21de0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
21df0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
21e00 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
21e10 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
21e20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
21e30 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
21e40 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
21e50 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
21e60 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
21e70 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
21e80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
21e90 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
21ea0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
21eb0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
21ec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
21ed0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
21ee0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
21ef0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
21f00 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
21f10 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
21f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
21f30 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
21f40 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
21f50 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
21f60 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
21f70 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
21f80 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
21f90 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
21fa0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
21fb0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
21fc0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
21fd0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
21fe0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
21ff0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
22000 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
22010 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
22020 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
22030 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
22040 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
22050 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
22060 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
22070 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
22080 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
22090 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
220a0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
220b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
220c0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
220d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
220e0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
220f0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
22100 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
22110 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
22120 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
22130 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
22140 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
22150 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
22160 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
22170 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
22180 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
22190 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
221a0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
221b0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
221c0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
221d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
221e0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
221f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22200 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22210 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
22220 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
22230 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
22240 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
22250 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
22260 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
22270 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
22280 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
22290 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
222a0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
222b0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
222c0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
222d0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
222e0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
222f0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
22300 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
22310 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
22320 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
22330 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
22340 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
22350 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22360 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
22370 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
22380 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
22390 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
223a0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
223b0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
223c0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
223d0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
223e0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
223f0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
22400 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
22410 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
22420 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
22430 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
22440 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
22450 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
22460 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then 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 65 74 75 72 6e 73 20 28  F,P,B) returns (
22490 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
224a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
224b0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
224c0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
224d0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
224e0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
224f0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
22500 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
22510 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
22520 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
22530 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
22540 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
22550 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
22560 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
22570 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
22580 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
22590 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
225a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
225b0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
225c0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
225d0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
225e0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
225f0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
22600 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
22610 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
22620 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
22630 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
22640 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
22650 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
22660 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
22670 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
22680 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
22690 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
226a0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
226b0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
226c0 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
226d0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
226e0 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
226f0 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
22700 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
22710 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
22720 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
22730 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
22740 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
22750 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
22760 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
22770 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
22780 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
22790 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
227a0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
227b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
227c0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
227d0 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
227e0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
227f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
22800 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
22810 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
22820 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
22830 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
22840 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
22850 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
22860 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
22870 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
22880 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22890 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
228a0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
228b0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
228c0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
228d0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
228e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
228f0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
22900 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
22910 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
22920 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
22930 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
22940 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
22950 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
22960 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
22970 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
22980 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
22990 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
229a0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
229b0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
229c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
229d0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
229e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
229f0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
22a00 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
22a10 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
22a20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
22a30 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
22a40 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
22a50 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
22a60 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
22a70 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
22a80 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
22a90 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
22aa0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
22ab0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
22ac0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
22ad0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
22ae0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
22af0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
22b00 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
22b10 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
22b20 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
22b30 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
22b40 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
22b50 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
22b60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
22b70 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
22b80 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
22b90 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
22ba0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
22bb0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
22bc0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
22bd0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
22be0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
22bf0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
22c00 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
22c10 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
22c20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
22c30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
22c40 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
22c50 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
22c60 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
22c70 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
22c80 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
22c90 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
22ca0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
22cb0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
22cc0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
22cd0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
22ce0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
22cf0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
22d00 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
22d10 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
22d20 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
22d30 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
22d40 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
22d50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
22d60 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
22d70 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
22d80 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
22d90 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
22da0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
22db0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
22dc0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
22dd0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
22de0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
22df0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
22e00 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
22e10 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
22e20 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
22e30 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
22e40 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
22e50 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
22e60 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
22e70 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
22e80 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
22e90 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
22ea0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
22eb0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
22ec0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
22ed0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
22ee0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
22ef0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
22f00 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
22f10 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
22f20 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
22f30 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
22f40 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
22f50 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
22f60 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
22f70 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
22f80 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
22f90 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
22fa0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
22fb0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
22fc0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
22fd0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
22fe0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22ff0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
23000 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
23010 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
23020 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
23030 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
23040 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
23050 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
23060 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23070 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
23080 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
23090 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
230a0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
230b0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
230c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
230d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
230e0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
230f0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
23100 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
23110 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
23120 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
23130 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
23140 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
23150 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
23160 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
23170 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
23180 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
23190 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
231a0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
231b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
231c0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
231d0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
231e0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
231f0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
23200 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
23210 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
23220 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
23230 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
23240 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
23250 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
23260 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
23270 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
23280 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
23290 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
232a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
232b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
232c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
232d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
232e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
232f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
23300 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
23310 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
23320 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
23330 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
23340 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
23350 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
23360 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
23370 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
23380 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
23390 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
233a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
233b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
233c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
233d0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
233e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
233f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
23400 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
23410 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
23420 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
23430 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
23440 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
23450 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
23460 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
23470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
23480 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
23490 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
234a0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
234b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
234c0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
234d0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
234e0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
234f0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
23500 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
23510 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
23520 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
23530 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
23540 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
23550 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
23560 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
23570 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
23580 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
23590 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
235a0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
235b0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
235c0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
235d0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
235e0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
235f0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
23600 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
23610 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
23620 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
23630 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
23640 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
23650 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
23660 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
23670 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
23680 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
23690 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
236a0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
236b0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
236c0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
236d0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
236e0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
236f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
23700 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
23710 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
23720 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
23730 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
23740 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
23750 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
23760 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
23770 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
23780 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
23790 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
237a0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
237b0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
237c0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
237d0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
237e0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
237f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
23800 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
23810 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
23820 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
23830 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
23840 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
23850 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
23860 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
23870 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
23880 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
23890 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
238a0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
238b0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
238c0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
238d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
238e0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
238f0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
23900 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
23910 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
23920 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
23930 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
23940 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
23950 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
23960 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
23970 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
23980 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
23990 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
239a0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
239b0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
239c0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
239d0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
239e0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
239f0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
23a00 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
23a10 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
23a20 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
23a30 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
23a40 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
23a50 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
23a60 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
23a70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23a80 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
23a90 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
23aa0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
23ab0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
23ac0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
23ad0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
23ae0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
23af0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
23b00 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
23b10 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
23b20 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
23b30 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
23b40 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
23b50 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
23b60 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
23b70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23b80 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
23b90 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
23ba0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
23bb0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
23bc0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
23bd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
23be0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
23bf0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
23c00 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
23c10 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
23c20 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
23c30 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
23c40 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
23c50 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
23c60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
23c70 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
23c80 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
23c90 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
23ca0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
23cb0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
23cc0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
23cd0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
23ce0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
23cf0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
23d00 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
23d10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23d20 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
23d30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
23d40 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
23d50 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
23d60 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
23d70 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
23d80 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
23d90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23da0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
23db0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
23dc0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
23dd0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
23de0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
23df0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
23e00 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
23e10 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23e20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
23e30 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
23e40 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
23e50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23e60 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
23e70 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
23e80 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
23e90 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
23ea0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
23eb0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
23ec0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23ed0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
23ee0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
23ef0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
23f00 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
23f10 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23f20 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
23f30 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
23f40 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
23f50 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
23f60 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
23f70 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
23f80 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
23f90 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
23fa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23fb0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
23fc0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
23fd0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
23fe0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
23ff0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24000 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
24010 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
24020 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
24030 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24040 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
24050 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
24060 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
24070 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24080 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24090 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
240a0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
240b0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
240c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
240d0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
240e0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
240f0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
24100 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
24110 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
24120 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
24130 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
24140 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
24150 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24160 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
24170 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
24180 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24190 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
241a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
241b0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
241c0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
241d0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
241e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
241f0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
24200 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
24210 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
24220 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24230 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
24240 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
24250 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
24260 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24270 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24280 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
24290 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
242a0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
242b0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
242c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
242d0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
242e0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
242f0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
24300 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
24310 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24320 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
24330 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
24340 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
24350 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
24360 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
24370 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
24380 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
24390 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
243a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
243b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
243c0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
243d0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
243e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
243f0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
24400 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24410 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
24420 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
24430 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
24440 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
24450 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
24460 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24470 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
24480 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
24490 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
244a0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
244b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
244c0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
244d0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
244e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
244f0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
24500 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
24510 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
24520 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
24530 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
24540 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24550 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
24560 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
24570 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24580 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
24590 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
245a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
245b0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
245c0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
245d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
245e0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
245f0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
24600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24610 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
24620 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
24630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24640 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
24650 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
24660 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24670 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
24680 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
24690 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
246a0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
246b0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
246c0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
246d0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
246e0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
246f0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
24700 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
24710 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
24720 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
24730 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
24740 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
24750 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24760 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
24770 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
24780 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
24790 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
247a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
247b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
247c0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
247d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
247e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
247f0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
24800 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
24810 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
24820 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
24830 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
24840 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
24850 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24860 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
24870 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
24880 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
24890 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
248a0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
248b0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
248c0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
248d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
248e0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
248f0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
24900 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
24910 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
24920 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
24930 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
24940 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
24950 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
24960 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
24970 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
24980 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
24990 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
249a0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
249b0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
249c0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
249d0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
249e0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
249f0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
24a00 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
24a10 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
24a20 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
24a30 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
24a40 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
24a50 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
24a60 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
24a70 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
24a80 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
24a90 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
24aa0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
24ab0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
24ac0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
24ad0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
24ae0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
24af0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
24b00 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
24b10 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
24b20 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
24b30 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
24b40 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
24b50 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
24b60 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
24b70 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
24b80 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
24b90 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
24ba0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
24bb0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
24bc0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
24bd0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
24be0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
24bf0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
24c00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
24c10 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
24c20 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
24c30 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
24c40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
24c50 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
24c60 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
24c70 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
24c80 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
24c90 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
24ca0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
24cb0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
24cc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24cd0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
24ce0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
24cf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24d00 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
24d10 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
24d20 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
24d30 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
24d40 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
24d50 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
24d60 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
24d70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
24d80 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
24d90 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
24da0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
24db0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
24dc0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
24dd0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
24de0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
24df0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
24e00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24e10 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
24e20 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
24e30 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
24e40 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
24e50 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
24e60 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
24e70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
24e80 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
24e90 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
24ea0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
24eb0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
24ec0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
24ed0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
24ee0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
24ef0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24f00 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
24f10 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
24f20 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
24f30 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
24f40 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
24f50 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
24f60 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
24f70 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
24f80 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
24f90 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
24fa0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
24fb0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
24fc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
24fd0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
24fe0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
24ff0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
25000 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
25010 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
25020 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
25030 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
25040 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
25050 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
25060 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
25070 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
25080 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
25090 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
250a0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
250b0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
250c0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
250d0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
250e0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
250f0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
25100 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
25110 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
25120 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
25130 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
25140 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
25150 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
25160 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
25170 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
25180 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25190 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
251a0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
251b0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
251c0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
251d0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
251e0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
251f0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
25200 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25210 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
25220 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
25230 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
25240 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
25250 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
25260 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
25270 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
25280 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
25290 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
252a0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
252b0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
252c0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
252d0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
252e0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
252f0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
25300 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
25310 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
25320 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
25330 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
25340 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
25350 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
25360 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
25370 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
25380 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
25390 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
253a0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
253b0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
253c0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
253d0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
253e0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
253f0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
25400 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
25410 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
25420 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
25430 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
25440 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
25450 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
25460 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
25470 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
25480 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
25490 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
254a0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
254b0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
254c0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
254d0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
254e0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
254f0 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
25500 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
25510 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
25520 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
25530 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
25540 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
25550 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
25560 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
25570 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
25580 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
25590 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
255a0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
255b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
255c0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
255d0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
255e0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
255f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25600 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
25610 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
25620 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
25630 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25640 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
25650 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
25660 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
25670 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25680 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25690 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
256a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
256b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
256c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
256d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
256e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
256f0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
25700 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25710 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25720 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
25730 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
25740 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
25750 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25760 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25770 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25780 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
25790 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
257a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
257b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
257c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
257d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
257e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
257f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
25800 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
25810 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
25820 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25830 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
25840 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25850 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25860 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25870 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
25880 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
25890 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
258a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
258b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
258c0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
258d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
258e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
258f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
25900 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
25910 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
25920 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
25930 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
25940 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
25950 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
25960 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
25970 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
25980 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
25990 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
259a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
259b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
259c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
259d0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
259e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
259f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
25a00 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25a10 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
25a20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
25a30 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
25a40 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
25a50 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25a60 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
25a70 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
25a80 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
25a90 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
25aa0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
25ab0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
25ac0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
25ad0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
25ae0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
25af0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
25b00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
25b10 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
25b20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
25b30 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
25b40 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
25b50 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
25b60 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
25b70 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
25b80 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
25b90 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
25ba0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
25bb0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
25bc0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
25bd0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
25be0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
25bf0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
25c00 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
25c10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25c20 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
25c30 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
25c40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25c50 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
25c60 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
25c70 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
25c80 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
25c90 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
25ca0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
25cb0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
25cc0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
25cd0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
25ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25cf0 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
25d00 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
25d10 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
25d20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
25d30 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
25d40 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
25d50 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
25d60 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
25d70 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
25d80 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
25d90 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
25da0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
25db0 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
25dc0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
25dd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
25de0 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
25df0 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
25e00 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
25e10 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
25e20 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
25e30 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
25e40 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
25e50 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
25e60 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
25e70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
25e80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
25e90 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
25ea0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
25eb0 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
25ec0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
25ed0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
25ee0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
25ef0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
25f00 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
25f10 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
25f20 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
25f30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
25f40 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
25f50 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
25f60 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
25f70 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
25f80 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
25f90 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
25fa0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
25fb0 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
25fc0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
25fd0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25fe0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
25ff0 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
26000 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
26010 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
26020 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
26030 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
26040 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
26050 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
26060 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
26070 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
26080 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
26090 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
260a0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
260b0 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
260c0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
260d0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
260e0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
260f0 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
26100 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
26110 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
26120 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
26130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26140 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
26150 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
26160 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
26170 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26180 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
26190 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
261a0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
261b0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
261c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
261d0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
261e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
261f0 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
26200 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
26210 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
26220 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
26230 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
26240 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
26250 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26260 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
26270 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
26280 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
26290 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
262a0 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
262b0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
262c0 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
262d0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
262e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
262f0 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
26300 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
26310 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
26320 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
26330 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
26340 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
26350 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
26360 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
26370 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
26380 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
26390 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
263a0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
263b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
263c0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
263d0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
263e0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
263f0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
26400 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
26410 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
26420 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
26430 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
26440 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
26450 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
26460 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
26470 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
26480 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
26490 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
264a0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
264b0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
264c0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
264d0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
264e0 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
264f0 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
26500 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
26510 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
26520 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
26530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
26540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26550 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
26560 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
26570 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
26580 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26590 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
265a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
265b0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
265c0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
265d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
265e0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
265f0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
26600 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
26610 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
26620 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
26630 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
26640 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
26650 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
26660 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
26670 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26680 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
26690 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
266a0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
266b0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
266c0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
266d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
266e0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
266f0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
26700 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
26710 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
26720 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
26730 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26740 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
26750 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
26760 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
26770 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
26780 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
26790 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
267a0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
267b0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
267c0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
267d0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
267e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
267f0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
26800 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26810 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
26820 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
26830 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
26840 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
26850 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
26860 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
26870 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
26880 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
26890 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
268a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
268b0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
268c0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
268d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
268e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
268f0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
26900 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
26910 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
26920 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
26930 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
26940 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
26950 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
26960 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
26970 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
26980 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
26990 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
269a0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
269b0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
269c0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
269d0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
269e0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
269f0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
26a00 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
26a10 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
26a20 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
26a30 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
26a40 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
26a50 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
26a60 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
26a70 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
26a80 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
26a90 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
26aa0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
26ab0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
26ac0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
26ad0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
26ae0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
26af0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
26b00 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
26b10 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
26b20 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
26b30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
26b40 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
26b50 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
26b60 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
26b70 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
26b80 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
26b90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26ba0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
26bb0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
26bc0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
26bd0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
26be0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
26bf0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
26c00 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
26c10 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
26c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26c30 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
26c40 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
26c50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
26c60 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
26c70 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
26c80 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
26c90 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
26ca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
26cb0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
26cc0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
26cd0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
26ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26cf0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
26d00 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
26d10 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
26d20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
26d30 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
26d40 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
26d50 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
26d60 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
26d70 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
26d80 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
26d90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26da0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
26db0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
26dc0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
26dd0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
26de0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
26df0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
26e00 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
26e10 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
26e20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26e30 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
26e40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
26e50 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
26e60 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
26e70 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
26e80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
26e90 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
26ea0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
26eb0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
26ec0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
26ed0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
26ee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
26ef0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
26f00 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
26f10 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
26f20 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
26f30 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
26f40 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
26f50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
26f60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
26f70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26f80 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
26f90 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
26fa0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
26fb0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
26fc0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
26fd0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
26fe0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
26ff0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
27000 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
27010 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
27020 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
27030 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
27040 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
27050 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
27060 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27070 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
27080 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
27090 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
270a0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
270b0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
270c0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
270d0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
270e0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
270f0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
27100 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
27110 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
27120 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
27130 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
27140 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
27150 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
27160 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
27170 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
27180 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
27190 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
271a0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
271b0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
271c0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
271d0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
271e0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
271f0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
27200 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
27210 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
27220 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
27230 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
27240 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
27250 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
27260 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
27270 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
27280 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
27290 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
272a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
272b0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
272c0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
272d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
272e0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
272f0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
27300 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
27310 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
27320 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
27330 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
27340 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
27350 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
27360 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
27370 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
27380 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
27390 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
273a0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
273b0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
273c0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
273d0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
273e0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
273f0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
27400 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
27410 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
27420 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
27430 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
27440 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27450 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
27460 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
27470 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
27480 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
27490 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
274a0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
274b0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
274c0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
274d0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
274e0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
274f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
27500 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
27510 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
27520 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
27530 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
27540 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
27550 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
27560 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
27570 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
27580 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
27590 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
275a0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
275b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
275c0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
275d0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
275e0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
275f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
27600 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
27610 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
27620 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
27630 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
27640 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
27650 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27660 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
27670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27680 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
27690 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
276a0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
276b0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
276c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
276d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
276e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
276f0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
27700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27710 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
27720 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
27730 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
27740 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
27750 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
27760 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
27770 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
27780 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
27790 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
277a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
277b0 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
277c0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
277d0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
277e0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
277f0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
27800 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
27810 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
27820 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
27830 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
27840 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
27850 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
27860 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
27870 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
27880 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
27890 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
278a0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
278b0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
278c0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
278d0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
278e0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
278f0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
27900 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
27910 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
27920 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
27930 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
27940 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
27950 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
27960 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
27970 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27980 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
27990 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
279a0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
279b0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
279c0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
279d0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
279e0 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
279f0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
27a00 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
27a10 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
27a20 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
27a30 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
27a40 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
27a50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
27a60 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
27a70 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
27a80 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
27a90 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
27aa0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
27ab0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
27ac0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
27ad0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
27ae0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
27af0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
27b00 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
27b10 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
27b20 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
27b30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
27b40 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
27b50 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
27b60 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
27b70 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
27b80 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
27b90 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
27ba0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
27bb0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
27bc0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
27bd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
27be0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27bf0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
27c00 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
27c10 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
27c20 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
27c30 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
27c40 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
27c50 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
27c60 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
27c70 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
27c80 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
27c90 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
27ca0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
27cb0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
27cc0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
27cd0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
27ce0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
27cf0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
27d00 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
27d10 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
27d20 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
27d30 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
27d40 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
27d50 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
27d60 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
27d70 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
27d80 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
27d90 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
27da0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
27db0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
27dc0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
27dd0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
27de0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
27df0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27e00 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
27e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
27e20 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
27e30 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
27e40 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
27e50 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
27e60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27e70 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
27e80 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
27e90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
27ea0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
27eb0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
27ec0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
27ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27ee0 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
27ef0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
27f00 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
27f10 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
27f20 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
27f30 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
27f40 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
27f50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
27f60 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
27f70 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
27f80 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
27f90 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
27fa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27fb0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
27fc0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
27fd0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
27fe0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
27ff0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
28000 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
28010 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
28020 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
28030 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
28040 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
28050 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
28060 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
28070 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
28080 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
28090 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
280a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
280b0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
280c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
280d0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
280e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
280f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28100 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
28110 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
28120 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28130 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
28140 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
28150 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
28160 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
28170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28180 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
28190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
281a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
281b0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
281c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
281d0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
281e0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
281f0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
28200 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
28210 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
28220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28230 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
28240 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
28250 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
28260 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
28270 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28280 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
28290 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
282a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
282b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
282c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
282d0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
282e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
282f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28300 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28310 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
28320 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
28330 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
28340 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
28350 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
28360 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
28370 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
28380 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
28390 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
283a0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
283b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
283c0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
283d0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
283e0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
283f0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
28400 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
28410 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
28420 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
28430 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
28440 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
28450 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
28460 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
28470 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
28480 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
28490 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
284a0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
284b0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
284c0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
284d0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
284e0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
284f0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
28500 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
28510 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
28520 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
28530 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
28540 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
28550 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
28560 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
28570 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
28580 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
28590 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
285a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
285b0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
285c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
285d0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
285e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
285f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28600 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
28610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
28620 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
28630 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
28640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
28650 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
28660 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
28670 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28680 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
28690 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
286a0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
286b0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
286c0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
286d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
286e0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
286f0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
28700 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
28710 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
28720 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
28730 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
28740 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
28750 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
28760 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
28770 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
28780 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
28790 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
287a0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
287b0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
287c0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
287d0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
287e0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
287f0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
28800 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
28810 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
28820 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
28830 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
28840 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
28850 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
28860 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
28870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
28880 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
28890 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
288a0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
288b0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
288c0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
288d0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
288e0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
288f0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
28900 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
28910 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
28920 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
28930 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
28940 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
28950 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
28960 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
28970 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
28980 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
28990 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
289a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
289b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
289c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
289d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
289e0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
289f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28a00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28a10 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
28a20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28a30 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
28a40 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
28a50 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
28a60 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
28a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28a90 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
28aa0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
28ab0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
28ac0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
28ad0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
28ae0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
28af0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
28b00 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
28b10 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
28b20 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
28b30 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
28b40 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
28b50 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
28b60 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
28b70 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
28b80 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
28b90 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
28ba0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
28bb0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
28bc0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
28bd0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
28be0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
28bf0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
28c00 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
28c10 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [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 69 6e 74 20 73 71  ex()]..*/.int sq
28cc0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28cd0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
28ce0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
28cf0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
28d00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28d10 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
28d20 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
28d30 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
28d40 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
28d50 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
28d60 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
28d70 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
28d80 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
28d90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
28da0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
28db0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28dc0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
28dd0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
28de0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
28df0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
28e00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28e10 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
28e20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
28e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28e40 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
28e50 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
28e60 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
28e70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
28e80 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
28e90 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
28ea0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
28eb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28ec0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
28ed0 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
28ee0 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
28ef0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
28f00 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
28f10 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
28f20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
28f30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
28f40 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
28f50 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
28f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
28f70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28f80 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
28f90 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
28fa0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
28fb0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
28fc0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
28fd0 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
28fe0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
28ff0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
29000 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29010 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
29020 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
29030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
29040 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
29050 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
29060 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
29070 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
29080 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
29090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
290a0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
290b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
290c0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
290d0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
290e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
290f0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
29100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
29110 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
29120 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
29130 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
29140 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
29150 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
29160 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
29170 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
29180 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
29190 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
291a0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
291b0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
291c0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
291d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
291e0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
291f0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
29200 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
29210 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29220 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
29230 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
29240 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
29250 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
29260 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
29270 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
29280 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
29290 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
292a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
292b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
292c0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
292d0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
292e0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
292f0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
29300 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
29310 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
29320 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
29330 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
29340 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
29350 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
29360 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
29370 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
29380 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
29390 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
293a0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
293b0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
293c0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
293d0 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
293e0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
293f0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
29400 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
29410 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
29420 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
29430 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
29440 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
29450 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
29460 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
29470 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
29480 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
29490 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
294a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
294b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
294c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
294d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
294e0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
294f0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
29500 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
29510 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
29520 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
29530 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
29540 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
29550 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
29560 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
29570 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
29580 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
29590 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
295a0 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
295b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
295c0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
295d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
295e0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
295f0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
29600 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
29610 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
29620 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
29630 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
29640 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
29650 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
29660 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
29670 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
29680 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
29690 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
296a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
296b0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
296c0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
296d0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
296e0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
296f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29700 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
29710 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29720 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
29730 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
29740 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
29750 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
29760 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
29770 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29780 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
29790 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
297a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
297b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
297c0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
297d0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
297e0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
297f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
29800 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
29810 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
29820 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
29830 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
29840 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
29850 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
29860 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29870 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
29880 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29890 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
298a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
298b0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
298c0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
298d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
298e0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
298f0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
29900 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
29910 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
29920 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
29930 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
29940 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
29950 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
29960 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
29970 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
29980 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29990 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
299a0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
299b0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
299c0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
299d0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
299e0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
299f0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
29a00 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
29a10 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
29a20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
29a30 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
29a40 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
29a50 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
29a60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
29a70 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
29a80 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
29a90 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
29aa0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
29ab0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
29ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
29ad0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
29ae0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
29af0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
29b00 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
29b10 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
29b20 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
29b30 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
29b40 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
29b50 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
29b60 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
29b70 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
29b80 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
29b90 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
29ba0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
29bb0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
29bc0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
29bd0 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
29be0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
29bf0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
29c00 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29c10 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
29c20 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
29c30 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
29c40 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
29c50 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
29c60 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
29c70 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
29c80 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
29c90 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
29ca0 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
29cb0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
29cc0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
29cd0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
29ce0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
29cf0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
29d00 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
29d10 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
29d20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
29d30 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
29d40 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
29d50 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
29d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
29d70 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
29d80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29d90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29da0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
29db0 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
29dc0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
29dd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29de0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
29df0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29e00 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
29e10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
29e20 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
29e30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29e40 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
29e50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29e60 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
29e70 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29e80 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
29ea0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
29eb0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
29ec0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29ed0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
29ee0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
29ef0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
29f00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
29f10 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
29f20 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
29f30 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
29f40 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
29f50 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
29f60 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
29f70 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
29f80 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
29f90 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
29fa0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
29fb0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
29fc0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
29fd0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
29fe0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
29ff0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2a000 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2a010 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2a020 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2a030 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2a040 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2a050 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2a060 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2a070 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2a080 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2a090 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2a0a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2a0b0 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2a0c0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2a0d0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2a0e0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2a0f0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2a100 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2a110 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2a120 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2a130 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2a140 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2a150 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2a160 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2a170 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2a180 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2a190 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2a1a0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2a1b0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2a1c0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2a1d0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2a1e0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2a1f0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2a200 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2a210 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2a220 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2a230 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2a240 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2a250 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2a260 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2a270 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2a280 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2a290 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2a2a0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2a2b0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2a2c0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2a2d0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2a2e0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2a2f0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2a300 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2a310 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2a320 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2a330 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2a340 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
2a350 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a360 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2a370 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a380 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2a390 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a3a0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2a3b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2a3c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a3d0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2a3e0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2a3f0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2a400 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2a410 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2a420 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2a430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a440 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2a450 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a460 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2a470 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a480 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2a490 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2a4a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a4b0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2a4c0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2a4d0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2a4e0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2a4f0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2a500 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2a510 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2a520 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2a530 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2a540 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2a550 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2a560 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2a570 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2a580 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2a590 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2a5a0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2a5b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a5c0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2a5d0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2a5e0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2a5f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2a600 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2a610 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2a620 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2a630 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2a640 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2a650 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2a660 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2a670 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2a680 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2a690 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2a6a0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2a6b0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2a6c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2a6d0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2a6e0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2a6f0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2a700 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2a710 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2a720 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a730 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2a740 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2a750 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2a760 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2a770 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2a780 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2a790 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2a7a0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2a7b0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2a7c0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2a7d0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2a7e0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2a7f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2a800 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2a810 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2a820 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2a830 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2a840 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2a850 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2a860 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2a870 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2a880 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2a890 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2a8a0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2a8b0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2a8c0 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2a8d0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2a8e0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2a8f0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2a900 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2a910 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2a920 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2a930 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2a940 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2a950 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2a960 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2a970 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2a980 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2a990 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2a9a0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2a9b0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2a9c0 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2a9d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2a9e0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2a9f0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2aa00 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2aa10 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2aa20 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2aa30 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2aa40 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2aa50 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2aa60 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2aa70 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2aa80 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2aa90 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2aaa0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2aab0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2aac0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2aad0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2aae0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2aaf0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2ab00 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2ab10 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2ab20 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2ab30 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2ab40 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2ab50 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2ab60 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2ab70 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2ab80 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2ab90 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2aba0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2abb0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2abc0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2abd0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2abe0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2abf0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2ac00 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2ac10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2ac20 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2ac30 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2ac40 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2ac50 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2ac60 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2ac70 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2ac80 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2ac90 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2aca0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2acb0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2acc0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2acd0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2ace0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2acf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ad00 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2ad10 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2ad20 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2ad30 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2ad40 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2ad50 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2ad60 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2ad70 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2ad80 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2ad90 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2ada0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2adb0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2adc0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2add0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2ade0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2adf0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2ae00 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2ae10 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2ae20 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2ae30 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2ae40 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2ae50 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2ae60 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2ae70 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2ae80 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2ae90 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2aea0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2aeb0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2aec0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2aed0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2aee0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2aef0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2af00 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2af10 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2af20 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2af30 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2af40 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2af50 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2af60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2af70 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2af80 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2af90 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2afa0 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2afb0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2afc0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2afd0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2afe0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2aff0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2b000 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2b010 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2b020 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2b030 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2b040 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2b050 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2b060 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2b070 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2b080 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2b090 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2b0a0 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2b0b0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2b0c0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2b0d0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2b0e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2b0f0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2b100 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2b110 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2b120 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2b130 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2b140 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2b150 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2b160 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2b170 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2b180 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2b190 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2b1a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2b1b0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2b1c0 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2b1d0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2b1e0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2b1f0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2b200 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2b210 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2b220 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2b230 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2b240 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2b250 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2b260 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2b270 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2b280 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2b290 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2b2a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2b2b0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2b2c0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2b2d0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2b2e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b2f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2b300 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2b310 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2b320 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2b330 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2b340 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2b350 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2b360 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2b370 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2b380 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2b390 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2b3a0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2b3b0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2b3c0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2b3d0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2b3e0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2b3f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2b400 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b410 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2b420 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2b430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b440 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b450 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2b460 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2b470 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2b480 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2b490 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2b4a0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2b4b0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2b4c0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2b4d0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2b4e0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2b4f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2b500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b520 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2b530 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2b540 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2b550 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2b560 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2b570 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2b580 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2b590 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2b5a0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2b5b0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2b5c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2b5d0 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2b5e0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2b5f0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2b600 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2b610 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2b620 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2b630 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2b640 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2b650 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2b660 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2b670 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2b680 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2b690 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2b6a0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2b6b0 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2b6c0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2b6d0 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2b6e0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b6f0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2b700 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2b710 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2b720 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2b730 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2b740 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2b750 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2b760 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2b770 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2b780 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2b790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b7a0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2b7b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2b7c0 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2b7d0 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2b7e0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2b7f0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2b800 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2b810 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2b820 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2b830 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2b840 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2b850 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2b860 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2b870 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2b880 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2b890 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2b8a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b8b0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b8c0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2b8d0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2b8e0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2b8f0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2b900 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2b910 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2b920 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2b930 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2b940 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2b950 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2b960 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2b970 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2b980 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2b990 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2b9a0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2b9b0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2b9c0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2b9d0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2b9e0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2b9f0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2ba00 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2ba10 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2ba20 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2ba30 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2ba40 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2ba50 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2ba60 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2ba70 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2ba80 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2ba90 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2baa0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2bab0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2bac0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2bad0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2bae0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2baf0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2bb00 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2bb10 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2bb20 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2bb30 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2bb40 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2bb50 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2bb60 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2bb70 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2bb80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2bb90 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2bba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2bbb0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2bbc0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2bbd0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2bbe0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2bbf0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2bc00 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2bc10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2bc20 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2bc30 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2bc40 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2bc50 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2bc60 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2bc70 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2bc80 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2bc90 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2bca0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2bcb0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2bcc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2bcd0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2bce0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bcf0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2bd00 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2bd10 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2bd20 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2bd30 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2bd40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bd50 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2bd60 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2bd70 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2bd80 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2bd90 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2bda0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2bdb0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2bdc0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2bdd0 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2bde0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2bdf0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2be00 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2be10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2be20 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2be30 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2be40 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2be50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2be60 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2be70 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2be80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2be90 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2bea0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2beb0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2bec0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2bed0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2bee0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2bef0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2bf00 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2bf10 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2bf20 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2bf30 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2bf40 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2bf50 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2bf60 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2bf70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bf80 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2bf90 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2bfa0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2bfb0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2bfc0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2bfd0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2bfe0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2bff0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2c000 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c010 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2c020 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2c030 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2c040 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2c050 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2c060 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2c070 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2c080 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c090 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2c0a0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2c0b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2c0c0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2c0d0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2c0e0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2c0f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2c100 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2c110 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2c120 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2c130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2c150 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2c160 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2c170 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2c180 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2c190 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2c1a0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2c1b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2c1c0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2c1d0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2c1e0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2c1f0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2c200 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2c210 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2c220 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2c230 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2c240 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2c250 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2c260 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2c270 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2c280 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2c290 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2c2a0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2c2b0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2c2c0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2c2d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2c2e0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c2f0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2c300 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2c310 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2c320 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2c330 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2c340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c350 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2c360 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2c370 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2c380 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2c390 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2c3a0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2c3b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c3c0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2c3d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2c3e0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2c3f0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2c400 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2c410 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2c420 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2c430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c440 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2c450 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2c460 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2c470 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c480 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2c490 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c4a0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2c4b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2c4c0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2c4d0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2c4e0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2c4f0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2c500 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2c510 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2c520 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2c530 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2c540 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2c550 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2c560 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c570 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2c580 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2c590 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c5a0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2c5b0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2c5c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2c5d0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2c5e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2c5f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2c600 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2c610 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2c620 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c630 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2c640 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c650 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2c660 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2c670 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2c680 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2c690 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c6a0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2c6b0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2c6c0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2c6d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c6e0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2c6f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2c700 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2c710 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2c720 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2c730 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2c740 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c750 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2c760 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c770 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2c780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c790 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2c7a0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2c7b0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2c7c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2c7d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2c7e0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2c7f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c800 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2c810 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2c820 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2c830 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2c840 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2c850 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2c860 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2c870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c880 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2c890 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c8a0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2c8b0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2c8c0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2c8d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2c8e0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2c8f0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2c900 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2c910 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2c920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c930 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2c940 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2c950 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2c960 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2c970 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2c980 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2c990 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2c9a0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2c9b0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2c9c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2c9d0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2c9e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2c9f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2ca00 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2ca10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ca20 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2ca30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2ca40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2ca50 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2ca60 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2ca70 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2ca80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2ca90 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2caa0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2cab0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cac0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2cad0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2cae0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2caf0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2cb00 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2cb10 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2cb20 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2cb30 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2cb40 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2cb50 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2cb60 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2cb70 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2cb80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2cb90 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2cba0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2cbb0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2cbc0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2cbd0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2cbe0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2cbf0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2cc00 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2cc10 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2cc20 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2cc30 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2cc40 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2cc50 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2cc60 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2cc70 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2cc80 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2cc90 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2cca0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2ccb0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2ccc0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2ccd0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2cce0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2ccf0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2cd00 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2cd10 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2cd20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2cd30 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2cd40 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2cd50 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2cd60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2cd70 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2cd80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2cd90 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2cda0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2cdb0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2cdc0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2cdd0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2cde0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2cdf0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2ce00 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2ce10 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2ce20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2ce30 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2ce40 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2ce50 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2ce60 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2ce70 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2ce80 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2ce90 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2cea0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2ceb0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2cec0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2ced0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2cee0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2cef0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2cf00 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2cf10 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2cf20 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2cf30 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2cf40 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2cf50 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2cf60 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2cf70 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2cf80 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2cf90 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2cfa0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2cfb0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2cfc0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2cfd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2cfe0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2cff0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2d000 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2d010 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2d020 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2d030 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2d040 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2d050 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2d060 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2d070 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2d080 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2d090 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2d0a0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2d0b0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2d0c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2d0d0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2d0e0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2d0f0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2d100 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2d110 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2d120 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2d130 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2d140 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2d150 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2d160 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2d170 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2d180 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2d190 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2d1a0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2d1b0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2d1c0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2d1d0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2d1e0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2d1f0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2d200 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2d210 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2d220 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2d230 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2d240 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2d250 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2d260 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2d270 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2d280 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2d290 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2d2a0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2d2b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2d2c0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2d2d0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2d2e0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2d2f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2d300 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2d310 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2d320 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2d330 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2d340 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2d350 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2d360 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2d370 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2d380 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2d390 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2d3a0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2d3b0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2d3c0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2d3d0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2d3e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2d3f0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2d400 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d410 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2d420 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2d430 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2d440 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2d450 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2d460 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2d470 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2d480 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2d490 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2d4a0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2d4b0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2d4c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2d4d0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2d4e0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2d4f0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2d500 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2d510 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2d520 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2d530 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2d540 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d550 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2d560 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d570 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2d580 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2d590 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2d5a0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2d5b0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2d5c0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2d5d0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2d5e0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2d5f0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2d600 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2d610 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2d620 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2d630 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2d640 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2d650 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2d660 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2d670 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2d680 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2d690 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2d6a0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2d6b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2d6c0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2d6d0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2d6e0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2d6f0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2d700 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2d710 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2d720 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2d730 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2d740 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2d750 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2d760 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2d770 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2d780 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2d790 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2d7a0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2d7b0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2d7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d7d0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2d7e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d7f0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2d800 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2d810 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2d820 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d830 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2d840 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2d850 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2d860 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2d870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d880 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2d890 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2d8a0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2d8b0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2d8c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2d8d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2d8e0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2d8f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d900 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2d910 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2d920 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2d930 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2d940 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2d950 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2d960 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2d970 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2d980 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2d990 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2d9a0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2d9b0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2d9c0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2d9d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d9e0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2d9f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2da00 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2da10 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2da20 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2da30 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2da40 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2da50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2da60 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2da70 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2da80 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2da90 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2daa0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2dab0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2dac0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2dad0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2dae0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2daf0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2db00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2db10 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2db20 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2db30 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2db40 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2db50 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2db60 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2db70 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2db80 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2db90 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2dba0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2dbb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2dbc0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2dbd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2dbe0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2dbf0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2dc00 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2dc10 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2dc20 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2dc30 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2dc40 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2dc50 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2dc60 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2dc70 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2dc80 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2dc90 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2dca0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2dcb0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2dcc0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2dcd0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2dce0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2dcf0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2dd00 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2dd10 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2dd20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2dd30 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2dd40 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2dd50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dd60 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2dd70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2dd80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2dd90 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2dda0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2ddb0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
2ddc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2ddd0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2dde0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2ddf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2de00 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2de10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2de20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2de30 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2de40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2de50 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2de60 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2de70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2de80 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2de90 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2dea0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2deb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2dec0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ded0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2dee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2def0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2df00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2df10 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2df20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2df30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2df40 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2df50 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2df60 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2df70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2df80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2df90 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2dfa0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2dfb0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2dfc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2dfd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2dfe0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2dff0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2e000 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2e010 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2e020 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2e030 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2e040 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2e050 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e060 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2e070 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2e080 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2e090 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2e0a0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2e0b0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2e0c0 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2e0d0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2e0e0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2e0f0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2e100 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2e110 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e120 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2e130 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2e140 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2e150 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2e160 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2e170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e180 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2e190 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2e1a0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2e1b0 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2e1c0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2e1d0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2e1e0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2e1f0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2e200 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2e210 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2e220 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
2e230 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
2e240 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
2e250 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
2e260 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2e270 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
2e280 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2e290 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
2e2a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
2e2b0 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
2e2c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e2d0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
2e2e0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
2e2f0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
2e300 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
2e310 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2e320 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
2e330 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
2e340 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
2e350 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2e360 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
2e370 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
2e380 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
2e390 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2e3a0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
2e3b0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
2e3c0 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
2e3d0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
2e3e0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
2e3f0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
2e400 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
2e410 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2e420 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2e430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e440 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2e450 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2e460 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2e470 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2e480 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2e490 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2e4a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e4b0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2e4c0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2e4d0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2e4e0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2e4f0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2e500 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2e510 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2e520 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2e530 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2e540 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2e550 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2e560 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2e570 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2e580 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2e590 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2e5a0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2e5b0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2e5c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2e5d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2e5e0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2e5f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2e600 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2e610 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2e620 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2e630 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2e640 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2e650 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2e660 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e670 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2e680 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2e690 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2e6a0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2e6b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2e6c0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2e6d0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2e6e0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2e6f0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2e700 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2e710 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2e720 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2e730 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2e740 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2e750 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2e760 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2e770 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2e780 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2e790 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2e7a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2e7b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2e7c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2e7d0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2e7e0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2e7f0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2e800 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2e810 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2e820 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2e830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e840 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2e850 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2e860 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2e870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e880 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2e890 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2e8a0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2e8b0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2e8c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2e8d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2e8e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e8f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2e900 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2e910 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e920 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2e930 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2e940 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2e950 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2e960 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2e970 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2e980 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2e990 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2e9a0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2e9b0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2e9c0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2e9d0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2e9e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2e9f0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2ea00 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2ea10 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2ea20 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2ea30 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2ea40 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2ea50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2ea60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2ea70 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2ea80 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2ea90 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2eaa0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2eab0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2eac0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2ead0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2eae0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2eaf0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2eb00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2eb10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2eb20 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2eb30 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2eb40 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2eb50 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2eb60 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2eb70 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2eb80 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2eb90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2eba0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2ebb0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2ebc0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2ebd0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2ebe0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2ebf0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ec00 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2ec10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ec20 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2ec30 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2ec40 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2ec50 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2ec60 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2ec70 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2ec80 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2ec90 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2eca0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2ecb0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2ecc0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2ecd0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2ece0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2ecf0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2ed00 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2ed10 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2ed20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2ed30 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2ed40 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2ed50 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2ed60 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2ed70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2ed80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2ed90 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2eda0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2edb0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2edc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2edd0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2ede0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2edf0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2ee00 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2ee10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2ee20 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2ee30 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2ee40 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2ee50 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2ee60 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2ee70 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2ee80 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2ee90 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2eea0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2eeb0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2eec0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2eed0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2eee0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2eef0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2ef00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ef10 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2ef20 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2ef30 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2ef40 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2ef50 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2ef60 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2ef70 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2ef80 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2ef90 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2efa0 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2efb0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2efc0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2efd0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2efe0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2eff0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2f000 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2f010 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2f020 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2f030 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2f040 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2f050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f060 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2f070 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f080 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2f090 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2f0a0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2f0b0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2f0c0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2f0d0 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2f0e0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2f0f0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2f100 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2f110 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2f120 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2f130 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2f140 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2f150 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2f160 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2f170 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2f180 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2f190 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2f1a0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2f1b0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2f1c0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2f1d0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2f1e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2f1f0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2f200 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2f210 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2f220 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2f230 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2f240 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2f250 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2f260 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2f270 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2f280 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2f290 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2f2a0 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2f2b0 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2f2c0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2f2d0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2f2e0 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2f2f0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2f300 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2f310 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2f320 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2f330 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2f340 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2f350 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2f360 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f370 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2f380 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2f390 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2f3a0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2f3b0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2f3c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2f3d0 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2f3e0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2f3f0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2f400 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2f410 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2f420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2f430 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2f440 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2f450 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2f460 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2f470 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2f480 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2f490 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2f4a0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2f4b0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2f4c0 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2f4d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2f4e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2f4f0 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2f500 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2f510 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2f520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2f530 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2f540 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2f550 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2f560 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2f570 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2f580 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2f590 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2f5a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2f5b0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2f5c0 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
2f5d0 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
2f5e0 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
2f5f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
2f600 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2f610 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
2f620 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
2f630 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2f640 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
2f650 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
2f660 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
2f670 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
2f680 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
2f690 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2f6a0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
2f6b0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
2f6c0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2f6d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2f6e0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2f6f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
2f700 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2f710 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2f720 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f730 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2f740 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2f750 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2f760 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2f770 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2f780 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2f790 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2f7a0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2f7b0 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
2f7c0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2f7d0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
2f7e0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2f7f0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2f800 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2f810 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2f820 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
2f830 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f840 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
2f850 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
2f860 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
2f870 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2f880 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2f890 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
2f8a0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
2f8b0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2f8c0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2f8d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
2f8e0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
2f8f0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2f900 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
2f910 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2f920 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2f930 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2f940 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
2f950 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2f960 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2f970 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2f980 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2f990 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2f9a0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2f9b0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2f9c0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2f9d0 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2f9e0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2f9f0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
2fa00 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2fa10 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2fa20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2fa30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2fa40 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
2fa50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fa60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2fa70 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
2fa80 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
2fa90 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
2faa0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
2fab0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
2fac0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
2fad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
2fae0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
2faf0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
2fb00 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
2fb10 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
2fb20 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2fb30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2fb40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2fb50 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2fb60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2fb70 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2fb80 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2fb90 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2fba0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2fbb0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2fbc0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fbd0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2fbe0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2fbf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2fc00 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2fc10 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2fc20 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2fc30 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2fc40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fc50 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2fc60 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2fc70 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2fc80 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2fc90 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2fca0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2fcb0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2fcc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2fcd0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2fce0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2fcf0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2fd00 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fd10 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2fd20 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2fd30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2fd40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2fd50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2fd60 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2fd70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2fd80 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2fd90 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2fda0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2fdb0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2fdc0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2fdd0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2fde0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2fdf0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2fe00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fe10 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2fe20 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2fe30 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2fe40 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
2fe50 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2fe60 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2fe70 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2fe80 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
2fe90 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2fea0 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2feb0 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2fec0 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2fed0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2fee0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2fef0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2ff00 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2ff10 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2ff20 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2ff30 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2ff40 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2ff50 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2ff60 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2ff70 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2ff80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ff90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2ffa0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2ffb0 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2ffc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ffd0 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2ffe0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2fff0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
30000 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30010 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
30020 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30030 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
30040 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
30050 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
30060 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
30070 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
30080 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
30090 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
300a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
300b0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
300c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
300d0 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
300e0 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
300f0 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
30100 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
30110 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
30120 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
30130 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
30140 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
30150 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
30160 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
30170 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
30180 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
30190 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
301a0 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
301b0 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
301c0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
301d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
301e0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
301f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
30200 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30210 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
30220 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
30230 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
30240 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30250 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
30260 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
30270 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
30280 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
30290 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
302a0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
302b0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
302c0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
302d0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
302e0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
302f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
30300 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
30310 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
30320 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
30330 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20  t64,int),.      
30340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30350 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
30360 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
30370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
30380 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
30390 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
303a0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
303b0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
303c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
303d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
303e0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
303f0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
30400 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
30410 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
30420 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
30430 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
30440 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
30450 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
30460 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
30470 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
30480 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
30490 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
304a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
304b0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
304c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
304d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
304e0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
304f0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
30500 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
30510 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
30520 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
30530 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
30540 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
30550 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
30560 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
30570 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30580 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
30590 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
305a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
305b0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
305c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
305d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
305e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
305f0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
30600 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
30610 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
30620 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
30630 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
30640 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
30650 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
30660 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30670 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
30680 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
30690 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
306a0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
306b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
306c0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
306d0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
306e0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
306f0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
30700 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
30710 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
30720 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
30730 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
30740 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
30750 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
30760 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
30770 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30780 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
30790 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
307a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
307b0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
307c0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
307d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
307e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
307f0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
30800 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
30810 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
30820 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
30830 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
30840 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
30850 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
30860 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
30870 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30880 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
30890 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
308a0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
308b0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
308c0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
308d0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
308e0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
308f0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
30900 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
30910 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
30920 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
30930 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
30940 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
30950 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
30960 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
30970 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
30980 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
30990 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
309a0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
309b0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
309c0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
309d0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
309e0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
309f0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
30a00 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
30a10 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
30a20 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
30a30 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
30a40 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
30a50 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
30a60 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
30a70 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
30a80 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
30a90 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
30aa0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
30ab0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
30ac0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
30ad0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
30ae0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
30af0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
30b00 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
30b10 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
30b20 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
30b30 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
30b40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
30b50 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
30b60 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
30b70 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
30b80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30b90 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
30ba0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
30bb0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
30bc0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
30bd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
30be0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
30bf0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
30c00 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
30c10 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
30c20 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
30c30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
30c40 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
30c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
30c60 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
30c70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30c80 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
30c90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
30ca0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
30cb0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
30cc0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
30cd0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
30ce0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
30cf0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
30d00 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
30d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30d30 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
30d40 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
30d50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
30d60 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
30d70 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
30d80 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
30d90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30da0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
30db0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
30dc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30dd0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
30de0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
30df0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
30e00 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
30e10 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
30e20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
30e30 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
30e40 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
30e50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30e60 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
30e70 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
30e80 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
30e90 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
30ea0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
30eb0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
30ec0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
30ed0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
30ee0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
30ef0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
30f00 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
30f10 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
30f20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
30f30 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
30f40 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
30f50 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
30f60 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
30f70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
30f80 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
30f90 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
30fa0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
30fb0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
30fc0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
30fd0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
30fe0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
30ff0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
31000 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
31010 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
31020 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
31030 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
31040 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
31050 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31060 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
31070 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31080 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
31090 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
310a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
310b0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
310c0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
310d0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
310e0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
310f0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
31100 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
31110 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
31120 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
31130 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
31140 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
31150 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
31160 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
31170 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
31180 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
31190 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
311a0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
311b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
311c0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
311d0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
311e0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
311f0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
31200 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
31210 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31220 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
31230 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
31240 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
31250 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
31260 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31270 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31280 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
31290 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
312a0 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
312b0 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
312c0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
312d0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
312e0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
312f0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
31300 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
31310 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
31320 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
31330 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
31340 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31350 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
31360 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
31370 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
31380 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
31390 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
313a0 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
313b0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
313c0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
313d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
313e0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
313f0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31400 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
31410 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
31420 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
31430 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
31440 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
31450 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
31460 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
31470 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
31480 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31490 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
314a0 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
314b0 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
314c0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
314d0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
314e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
314f0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
31500 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
31510 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31520 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
31530 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
31540 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
31550 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
31560 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
31570 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
31580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
31590 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
315a0 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
315b0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
315c0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
315d0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
315e0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
315f0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
31600 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
31610 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
31620 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
31630 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
31640 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
31650 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
31660 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
31670 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
31680 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
31690 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
316a0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
316b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
316c0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
316d0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
316e0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
316f0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
31700 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
31710 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
31720 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
31730 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
31740 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
31750 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
31760 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
31770 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
31780 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31790 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
317a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
317b0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
317c0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
317d0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
317e0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
317f0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
31800 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
31810 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
31820 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
31830 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
31840 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
31850 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31860 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
31870 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
31880 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
31890 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
318a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
318b0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
318c0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
318d0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
318e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
318f0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
31900 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
31910 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
31920 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
31930 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31940 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
31950 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
31960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
31970 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
31980 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
31990 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
319a0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
319b0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
319c0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
319d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
319e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
319f0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
31a00 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
31a10 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
31a20 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
31a30 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
31a40 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
31a50 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
31a60 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
31a70 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
31a80 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
31a90 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
31aa0 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
31ab0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
31ac0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
31ad0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
31ae0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
31af0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
31b00 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
31b10 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
31b20 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
31b30 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
31b40 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
31b50 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
31b60 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
31b70 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
31b80 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
31b90 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
31ba0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
31bb0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
31bc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
31bd0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
31be0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
31bf0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
31c00 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
31c10 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
31c20 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
31c30 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
31c40 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
31c50 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
31c60 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
31c70 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
31c80 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
31c90 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
31ca0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
31cb0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
31cc0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
31cd0 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
31ce0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
31cf0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
31d00 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
31d10 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
31d20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
31d30 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
31d40 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
31d50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
31d60 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
31d70 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
31d80 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
31d90 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
31da0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
31db0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
31dc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31dd0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
31de0 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
31df0 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
31e00 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
31e10 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
31e20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
31e30 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
31e40 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
31e50 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
31e60 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
31e70 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
31e80 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
31e90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
31ea0 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
31eb0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
31ec0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
31ed0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
31ee0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
31ef0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
31f00 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
31f10 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
31f20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
31f30 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
31f40 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
31f50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31f60 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
31f70 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
31f80 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
31f90 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
31fa0 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
31fb0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
31fc0 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
31fd0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
31fe0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
31ff0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
32000 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
32010 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
32020 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
32030 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
32040 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
32050 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
32060 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
32070 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
32080 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
32090 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
320a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
320b0 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
320c0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
320d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
320e0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
320f0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
32100 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
32110 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
32120 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
32130 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
32140 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
32150 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
32160 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
32170 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
32180 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
32190 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
321a0 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
321b0 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
321c0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
321d0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
321e0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
321f0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
32200 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
32210 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
32220 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
32230 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
32240 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
32250 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
32260 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
32270 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
32280 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
32290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
322a0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
322b0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
322c0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
322d0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
322e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
322f0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
32300 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
32310 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
32320 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
32330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
32340 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
32350 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
32360 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
32370 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
32380 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
32390 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
323a0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
323b0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
323c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
323d0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
323e0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
323f0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
32400 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
32410 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
32420 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
32430 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
32440 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
32450 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
32460 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
32470 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
32480 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
32490 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
324a0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
324b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
324c0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
324d0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
324e0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
324f0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
32500 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
32510 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
32520 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
32530 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
32540 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
32550 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
32560 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
32570 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
32580 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
32590 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
325a0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
325b0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
325c0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
325d0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
325e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
325f0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
32600 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
32610 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
32620 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
32630 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
32640 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
32650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32660 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
32670 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
32680 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
32690 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
326a0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
326b0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
326c0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
326d0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
326e0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
326f0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
32700 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32710 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
32720 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32730 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
32740 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
32750 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
32760 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
32770 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
32780 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
32790 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
327a0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
327b0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
327c0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
327d0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
327e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
327f0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
32800 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
32810 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
32820 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
32830 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
32840 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32850 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
32860 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
32870 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
32880 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
32890 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
328a0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
328b0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
328c0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
328d0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
328e0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
328f0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
32900 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
32910 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
32920 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32930 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
32940 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
32950 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
32960 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
32970 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32980 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32990 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
329a0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
329b0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
329c0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
329d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
329e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
329f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
32a10 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
32a20 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
32a30 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
32a40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32a50 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
32a60 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
32a70 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
32a80 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
32a90 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
32aa0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32ab0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
32ac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32ad0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
32ae0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
32af0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
32b00 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
32b10 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
32b20 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
32b30 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
32b40 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
32b50 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
32b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32b70 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
32b80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32b90 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
32ba0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
32bb0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
32bc0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
32bd0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
32be0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
32bf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32c00 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
32c10 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
32c20 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
32c30 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
32c40 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
32c50 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
32c60 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
32c70 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
32c80 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
32c90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32ca0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
32cb0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
32cc0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
32cd0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
32ce0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
32cf0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
32d00 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
32d10 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
32d20 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
32d30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
32d40 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
32d50 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
32d60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32d70 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
32d80 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
32d90 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
32da0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
32db0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
32dc0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
32dd0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
32de0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
32df0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32e00 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
32e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32e20 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
32e30 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
32e40 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
32e50 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
32e60 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
32e70 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
32e80 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
32e90 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
32ea0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
32eb0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
32ec0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
32ed0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
32ee0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32ef0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
32f00 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
32f10 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
32f20 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
32f30 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
32f40 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
32f50 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
32f60 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
32f70 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
32f80 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
32f90 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32fa0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
32fb0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
32fc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32fd0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
32fe0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
32ff0 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
33000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33010 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33020 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
33030 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
33040 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
33050 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
33060 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
33070 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
33080 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
33090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
330a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
330b0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
330c0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
330d0 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
330e0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
330f0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
33100 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
33110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33120 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
33130 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33140 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
33150 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
33160 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33170 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
33180 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
33190 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
331a0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
331b0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
331c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
331d0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
331e0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
331f0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
33200 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
33210 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33220 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
33230 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
33240 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
33250 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
33260 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
33270 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33280 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
33290 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
332a0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
332b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
332c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
332d0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
332e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
332f0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
33300 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33310 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
33320 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
33330 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
33340 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
33350 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
33360 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
33370 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
33380 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33390 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
333a0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
333b0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
333c0 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
333d0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
333e0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
333f0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
33400 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
33410 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
33420 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
33430 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
33440 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
33450 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
33460 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
33470 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
33480 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33490 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
334a0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
334b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
334c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
334d0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
334e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
334f0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
33500 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
33510 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33520 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
33530 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
33540 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
33550 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
33560 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
33570 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
33580 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
33590 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
335a0 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
335b0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
335c0 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
335d0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
335e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
335f0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
33600 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33610 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
33620 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
33630 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
33640 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
33650 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
33660 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
33670 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
33680 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
33690 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
336a0 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
336b0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
336c0 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
336d0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
336e0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
336f0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
33700 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
33710 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
33720 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
33730 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
33740 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
33750 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
33760 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
33770 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
33780 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
33790 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
337a0 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
337b0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
337c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
337d0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
337e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
337f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33800 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
33810 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
33820 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
33830 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
33840 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
33850 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
33860 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
33870 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
33880 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
33890 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
338a0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
338b0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
338c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
338d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
338e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
338f0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
33900 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
33910 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
33920 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
33930 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
33940 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
33950 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
33960 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
33970 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
33980 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
33990 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
339a0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
339b0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
339c0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
339d0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
339e0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
339f0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
33a00 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
33a10 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
33a20 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
33a30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
33a40 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
33a50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33a60 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
33a70 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
33a80 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
33a90 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
33aa0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
33ab0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
33ac0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
33ad0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
33ae0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
33af0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
33b00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33b10 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
33b20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33b30 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
33b40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33b50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33b60 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
33b70 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
33b80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33b90 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
33ba0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
33bb0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
33bc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33bd0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
33be0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
33bf0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
33c00 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
33c10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
33c20 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
33c30 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
33c40 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
33c50 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
33c60 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
33c70 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
33c80 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
33c90 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
33ca0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33cb0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
33cc0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
33cd0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
33ce0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33cf0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
33d00 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
33d10 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
33d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33d30 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
33d40 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
33d50 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
33d60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
33d70 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
33d80 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
33d90 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
33da0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
33db0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
33dc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33dd0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
33de0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
33df0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
33e00 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
33e10 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
33e20 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
33e30 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
33e40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33e50 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
33e60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33e70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33e80 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
33e90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
33ea0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
33eb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33ec0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
33ed0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
33ee0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33ef0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33f00 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
33f10 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
33f20 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
33f30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33f40 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
33f50 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
33f60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33f70 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
33f80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
33f90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33fa0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
33fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33fc0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
33fd0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
33fe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33ff0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
34000 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
34010 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34020 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
34030 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34040 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
34050 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
34060 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34070 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
34080 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
34090 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
340a0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
340b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
340c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
340d0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
340e0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
340f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34100 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34110 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
34120 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
34130 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
34140 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34150 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34160 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
34170 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34180 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
34190 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
341a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
341b0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
341c0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
341d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
341e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
341f0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
34200 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
34210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34220 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
34230 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
34240 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
34250 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
34260 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
34270 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
34280 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
34290 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
342a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
342b0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
342c0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
342d0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
342e0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
342f0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
34300 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
34310 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
34320 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
34330 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34340 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
34350 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
34360 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
34370 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
34380 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
34390 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
343a0 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
343b0 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
343c0 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
343d0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
343e0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
343f0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
34400 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
34410 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
34420 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
34430 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
34440 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
34450 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
34460 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
34470 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
34480 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34490 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
344a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
344b0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
344c0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
344d0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
344e0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
344f0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
34500 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
34510 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
34520 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
34530 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
34540 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
34550 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
34560 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
34570 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
34580 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
34590 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
345a0 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
345b0 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
345c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
345d0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
345e0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
345f0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
34600 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
34610 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
34620 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
34630 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
34640 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
34650 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
34660 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34670 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
34680 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
34690 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
346a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
346b0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
346c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
346d0 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
346e0 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
346f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
34700 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
34710 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
34720 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
34730 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
34740 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
34750 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
34760 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
34770 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
34780 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
34790 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
347a0 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
347b0 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
347c0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
347d0 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
347e0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
347f0 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
34800 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
34810 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
34820 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
34830 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
34840 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34850 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
34860 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
34870 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
34880 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
34890 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
348a0 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
348b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
348c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
348d0 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
348e0 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
348f0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
34900 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
34910 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
34920 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
34930 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
34940 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
34950 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
34960 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
34970 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
34980 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
34990 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
349a0 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
349b0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
349c0 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
349d0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
349e0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
349f0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
34a00 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
34a10 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
34a20 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
34a30 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
34a40 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
34a50 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
34a60 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
34a70 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
34a80 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
34a90 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
34aa0 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
34ab0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
34ac0 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
34ad0 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
34ae0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
34af0 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
34b00 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
34b10 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
34b20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34b30 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
34b40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
34b50 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
34b60 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
34b70 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
34b80 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
34b90 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
34ba0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
34bb0 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
34bc0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
34bd0 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
34be0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
34bf0 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
34c00 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
34c10 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
34c20 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34c30 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
34c40 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
34c50 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
34c60 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34c70 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
34c80 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
34c90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
34ca0 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
34cb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
34cc0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
34cd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34ce0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
34cf0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34d00 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
34d10 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
34d20 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
34d30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
34d40 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
34d50 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
34d60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
34d70 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
34d80 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
34d90 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
34da0 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
34db0 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
34dc0 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
34dd0 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
34de0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
34df0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
34e00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
34e10 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
34e20 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
34e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
34e40 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
34e50 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
34e60 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
34e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34e80 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
34e90 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
34ea0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
34eb0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
34ec0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34ed0 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
34ee0 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
34ef0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
34f00 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
34f10 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
34f20 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
34f30 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34f40 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
34f50 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
34f60 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
34f70 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
34f80 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
34f90 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
34fa0 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
34fb0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
34fc0 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
34fd0 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
34fe0 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
34ff0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
35000 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
35010 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
35020 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
35030 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
35040 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35050 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
35060 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35070 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
35080 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
35090 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
350a0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
350b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
350c0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
350d0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
350e0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
350f0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
35100 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
35110 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
35120 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35130 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
35140 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
35150 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
35160 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
35170 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
35180 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
35190 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
351a0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
351b0 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
351c0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
351d0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
351e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
351f0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
35200 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
35210 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
35220 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
35230 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
35240 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
35250 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
35260 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
35270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35280 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
35290 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
352a0 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
352b0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
352c0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
352d0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
352e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
352f0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
35300 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
35310 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
35320 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
35330 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
35340 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
35350 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
35360 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
35370 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
35380 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
35390 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
353a0 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
353b0 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
353c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
353d0 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
353e0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
353f0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
35400 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
35410 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
35420 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
35430 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
35440 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
35450 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
35460 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
35470 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
35480 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
35490 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
354a0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
354b0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
354c0 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
354d0 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
354e0 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
354f0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
35500 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
35510 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
35520 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35530 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
35540 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
35550 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
35560 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35570 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
35580 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35590 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
355a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
355b0 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
355c0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
355d0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
355e0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
355f0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
35600 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
35610 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
35620 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
35630 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
35640 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
35650 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
35660 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
35670 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
35680 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35690 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
356a0 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
356b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
356c0 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
356d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
356e0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
356f0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
35700 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
35710 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
35720 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
35730 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35740 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
35750 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
35760 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35770 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  v2()]..*/.int sq
35780 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35790 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
357a0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
357b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
357c0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
357d0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
357e0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
357f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35800 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
35810 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
35820 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
35830 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
35840 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
35850 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
35860 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
35870 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
35880 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
35890 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
358a0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
358b0 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
358c0 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
358d0 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
358e0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
358f0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
35900 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
35910 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
35920 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
35930 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
35940 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
35950 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
35960 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
35970 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
35980 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
35990 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
359a0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
359b0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
359c0 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
359d0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
359e0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
359f0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
35a00 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
35a10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
35a20 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
35a30 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
35a40 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
35a50 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
35a60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
35a70 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
35a80 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
35a90 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35aa0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
35ab0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
35ac0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
35ad0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
35ae0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
35af0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
35b00 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
35b10 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
35b20 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
35b30 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
35b40 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
35b50 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
35b60 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
35b70 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
35b80 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
35b90 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
35ba0 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
35bb0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
35bc0 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
35bd0 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
35be0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
35bf0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
35c00 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
35c10 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
35c20 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
35c30 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
35c40 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
35c50 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
35c60 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
35c70 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
35c80 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
35c90 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
35ca0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
35cb0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
35cc0 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
35cd0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
35ce0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
35cf0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
35d00 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
35d10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
35d20 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
35d30 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
35d40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35d50 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
35d60 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
35d70 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
35d80 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
35d90 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
35da0 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
35db0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
35dc0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
35dd0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
35de0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
35df0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
35e00 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
35e10 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
35e20 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
35e30 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
35e40 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
35e50 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
35e60 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
35e70 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
35e80 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
35e90 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
35ea0 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
35eb0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
35ec0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
35ed0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
35ee0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
35ef0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
35f00 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
35f10 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
35f20 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
35f30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
35f40 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
35f50 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
35f60 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
35f70 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
35f80 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
35f90 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
35fa0 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
35fb0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
35fc0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
35fd0 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
35fe0 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
35ff0 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
36000 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
36010 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
36020 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
36030 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36040 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
36050 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
36060 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
36070 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
36080 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
36090 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
360a0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
360b0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
360c0 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
360d0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
360e0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
360f0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
36100 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
36110 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
36120 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
36130 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
36140 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
36150 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
36160 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
36170 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
36180 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
36190 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
361a0 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
361b0 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
361c0 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
361d0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
361e0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
361f0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
36200 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
36210 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
36220 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
36230 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
36240 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
36250 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
36260 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
36270 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
36280 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
36290 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
362a0 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
362b0 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
362c0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
362d0 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
362e0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
362f0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
36300 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
36310 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
36320 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
36330 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
36340 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
36350 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
36360 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
36370 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
36380 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
36390 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
363a0 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
363b0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
363c0 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
363d0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
363e0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
363f0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
36400 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
36410 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
36420 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
36430 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
36440 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
36450 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
36460 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
36470 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
36480 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
36490 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
364a0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
364b0 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
364c0 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
364d0 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
364e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
364f0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
36500 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
36510 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
36520 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
36530 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
36540 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
36550 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
36560 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36570 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
36580 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
36590 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
365a0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
365b0 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
365c0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
365d0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
365e0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
365f0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
36600 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
36610 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
36620 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
36630 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
36640 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
36650 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
36660 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
36670 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
36680 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
36690 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
366a0 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
366b0 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
366c0 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
366d0 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
366e0 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
366f0 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
36700 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
36710 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
36720 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
36730 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
36740 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
36750 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
36760 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
36770 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
36780 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
36790 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
367a0 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
367b0 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
367c0 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
367d0 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
367e0 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
367f0 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
36800 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
36810 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
36820 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
36830 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
36840 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
36850 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
36860 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
36870 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
36880 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
36890 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
368a0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
368b0 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
368c0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
368d0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
368e0 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
368f0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
36900 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
36910 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
36920 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
36930 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
36940 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
36950 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
36960 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
36970 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
36980 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
36990 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
369a0 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
369b0 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
369c0 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
369d0 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
369e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
369f0 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
36a00 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
36a10 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
36a20 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
36a30 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
36a40 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
36a50 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
36a60 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
36a70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
36a80 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
36a90 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
36aa0 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
36ab0 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
36ac0 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
36ad0 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
36ae0 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
36af0 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
36b00 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
36b10 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
36b20 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
36b30 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
36b40 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
36b50 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
36b60 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
36b70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36b80 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
36b90 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
36ba0 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
36bb0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
36bc0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
36bd0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
36be0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
36bf0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
36c00 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
36c10 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
36c20 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
36c30 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
36c40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36c50 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
36c60 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
36c70 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
36c80 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
36c90 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
36ca0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36cb0 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
36cc0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
36cd0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
36ce0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
36cf0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
36d00 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
36d10 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
36d20 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
36d30 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
36d40 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
36d50 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
36d60 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
36d70 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36d80 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
36d90 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
36da0 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
36db0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
36dc0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
36dd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
36de0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
36df0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
36e00 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36e10 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
36e20 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
36e30 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
36e40 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
36e50 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
36e60 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
36e70 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
36e80 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
36e90 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
36ea0 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
36eb0 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
36ec0 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
36ed0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
36ee0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
36ef0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
36f00 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
36f10 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
36f20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
36f30 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
36f40 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
36f50 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
36f60 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
36f70 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
36f80 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36f90 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
36fa0 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
36fb0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
36fc0 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f  te3_data_directo
36fd0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
36fe0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
36ff0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
37000 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
37010 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
37020 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37030 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
37040 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37050 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
37060 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
37070 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
37080 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
37090 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
370a0 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
370b0 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
370c0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
370d0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
370e0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
370f0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
37100 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
37110 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
37120 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
37130 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
37140 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
37150 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
37160 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
37170 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
37180 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
37190 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
371a0 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
371b0 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
371c0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
371d0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
371e0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
371f0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
37200 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
37210 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
37220 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
37230 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
37240 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
37250 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
37260 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
37270 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
37280 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
37290 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
372a0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
372b0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
372c0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
372d0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
372e0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
372f0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
37300 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
37310 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
37320 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
37330 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
37340 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
37350 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
37360 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
37370 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
37380 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
37390 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
373a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
373b0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
373c0 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
373d0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
373e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
373f0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
37400 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37410 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37420 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
37430 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
37440 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37450 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
37460 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37470 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
37480 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
37490 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
374a0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
374b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
374c0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
374d0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
374e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
374f0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
37500 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
37510 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
37520 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
37530 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
37540 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
37550 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
37560 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
37570 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
37580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
37590 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61  eturn The Filena
375a0 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73  me For A Databas
375b0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
375c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
375d0 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29  db_filename(D,N)
375e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
375f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
37600 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73  a filename.** as
37610 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61  sociated with da
37620 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e  tabase N of conn
37630 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20  ection D.  ^The 
37640 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
37650 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61  le.** has the na
37660 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74  me "main".  If t
37670 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63  here is no attac
37680 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f  hed database N o
37690 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
376a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  * connection D, 
376b0 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e  or if database N
376c0 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20   is a temporary 
376d0 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  or in-memory dat
376e0 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61  abase, then.** a
376f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
37700 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
37710 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72   ^The filename r
37720 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
37730 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20  function is the 
37740 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a  output of the.**
37750 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d   xFullPathname m
37760 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46  ethod of the [VF
37770 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77  S].  ^In other w
37780 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61  ords, the filena
37790 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e  me.** will be an
377a0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61   absolute pathna
377b0 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20  me, even if the 
377c0 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a  filename used.**
377d0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
377e0 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79  abase originally
377f0 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72 65   was a URI or re
37800 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e  lative pathname.
37810 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
37820 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
37830 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ame(sqlite3 *db,
37840 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
37850 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
37860 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
37870 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
37880 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a  is read-only.**.
37890 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
378a0 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29  db_readonly(D,N)
378b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
378c0 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61  ns 1 if the data
378d0 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e  base N.** of con
378e0 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61  nection D is rea
378f0 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20  d-only, 0 if it 
37900 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f  is read/write, o
37910 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74  r -1 if N is not
37920 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
37930 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f  a database on co
37940 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69  nnection D..*/.i
37950 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  nt sqlite3_db_re
37960 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a  adonly(sqlite3 *
37970 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  db, const char *
37980 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a  zDbName);../*.**
37990 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
379a0 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
379b0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d statement.**.*
379c0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
379d0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
379e0 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
379f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37a00 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
37a10 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
37a20 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
37a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
37a40 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73  b.  ^If pStmt is
37a50 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
37a60 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37a70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37a80 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
37a90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
37aa0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
37ab0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
37ac0 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
37ad0 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20  ^If no prepared 
37ae0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
37af0 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
37b00 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
37b10 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
37b20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
37b30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37b40 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
37b50 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
37b60 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  * [sqlite3_next_
37b70 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
37b80 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
37b90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37ba0 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
37bb0 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
37bc0 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
37bd0 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
37be0 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
37bf0 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
37c00 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
37c10 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
37c20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
37c30 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
37c40 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
37c50 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
37c60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
37c70 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
37c80 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
37c90 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
37ca0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
37cb0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
37cc0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f  ansaction is [CO
37cd0 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64  MMIT | committed
37ce0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
37cf0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
37d00 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
37d10 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
37d20 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
37d30 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
37d40 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
37d50 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73  idden..** ^The s
37d60 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
37d70 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
37d80 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
37d90 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
37da0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
37db0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
37dc0 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42  action is [ROLLB
37dd0 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63  ACK | rolled bac
37de0 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  k]..** ^Any call
37df0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
37e00 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
37e10 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
37e20 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
37e30 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
37e40 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
37e50 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
37e60 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
37e70 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
37e80 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
37e90 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  k..** ^If the ca
37ea0 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
37eb0 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
37ec0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
37ed0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
37ee0 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
37ef0 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
37f00 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ck..**.** ^The s
37f10 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37f20 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71  ok(D,C,P) and sq
37f30 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37f40 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
37f50 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ions.** return t
37f60 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
37f70 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
37f80 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65  call of the same
37f90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20   function.** on 
37fa0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
37fb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
37fc0 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
37fd0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
37fe0 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f  for each functio
37ff0 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68  n on D..**.** Th
38000 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c  e commit and rol
38010 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62  lback hook callb
38020 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65 65  acks are not ree
38030 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63  ntrant..** The c
38040 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
38050 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
38060 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
38070 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
38080 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
38090 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
380a0 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
380b0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
380c0 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
380d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
380e0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
380f0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
38100 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
38110 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
38120 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
38130 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
38140 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
38150 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
38160 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
38170 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
38180 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65  running any othe
38190 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
381a0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45  , including SELE
381b0 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a  CT statements,.*
381c0 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c  * or merely call
381d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
381e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
381f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
38200 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
38210 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
38220 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
38230 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
38240 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
38250 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
38260 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
38270 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
38280 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
38290 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
382a0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
382b0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
382c0 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
382d0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
382e0 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
382f0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
38300 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
38310 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
38320 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
38330 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
38340 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
38350 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
38360 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
38370 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
38380 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
38390 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
383a0 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
383b0 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
383c0 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
383d0 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
383e0 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
383f0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
38400 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
38410 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
38420 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
38430 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
38440 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
38450 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
38460 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
38470 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
38480 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
38490 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
384a0 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
384b0 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
384c0 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
384d0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
384e0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
384f0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
38500 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
38510 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
38520 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
38530 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
38540 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  osed..**.** See 
38550 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
38560 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
38570 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76   interface..*/.v
38580 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
38590 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
385a0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
385b0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
385c0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
385d0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
385e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
385f0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
38600 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
38610 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
38620 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
38630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38640 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
38650 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
38660 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
38670 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
38680 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38690 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
386a0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
386b0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
386c0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
386d0 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
386e0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
386f0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e   deleted..** ^An
38700 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
38710 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
38720 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
38730 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
38740 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
38750 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
38760 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dden..**.** ^The
38770 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
38780 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
38790 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
387a0 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
387b0 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
387c0 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
387d0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66  leted..** ^The f
387e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
387f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
38800 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
38810 68 69 7